Skip to main content

Troubleshooting

Common deploy failures and their fixes.

Customization API Errors​

404 on /CustomizationApi/Import​

Cause: Wrong HTTP method or URL casing.

Fix: All Customization API endpoints require POST. The URL is case-sensitive:

  • Correct: /CustomizationApi/Import (capital I)
  • Wrong: /CustomizationApi/import, /customizationapi/Import

405 Method Not Allowed​

Cause: Using GET or PUT instead of POST.

Fix: Every Customization API endpoint uses POST, including publishEnd (which takes an empty JSON body {}).

publishEnd returns HTTP 400​

This is expected. publishEnd returns:

  • HTTP 200 → still publishing (keep polling)
  • HTTP 400 with isCompleted: true → publish finished
  • HTTP 400 with isFailed: true → publish failed (check log entries in response)

C# Compilation Errors​

CS0246: Type or namespace not found​

Common causes:

  • Referencing ARCustomerClass (not a public type in 24.2)
  • Missing using statement
  • Referencing a type from an ISV package that isn't co-published

Fix: Check the exact type name against the Acumatica API reference. Use fully qualified names when uncertain.

GetExtension failure on inquiry DACs​

Cause: Inquiry/projection DACs (like InventoryAllocDetEnqResult) are virtual types. Cache extensions on these DACs can fail if the base type isn't properly initialized.

Fix: Ensure your extension class is simple — avoid complex field initializations. Test on the actual screen (IN402000) after publish.

Database Column Issues​

NullReferenceException during publish​

Cause: <Table> elements in the project XML.

Fix: Remove ALL <Table> elements. Use <Sql> with ALTER TABLE ADD and IF NOT EXISTS guards instead. DAC [PXDB*] attributes handle column creation during publish.

CREATE TABLE silently fails on cloud​

Cause: Acumatica cloud blocks CREATE TABLE during customization publish.

Fix: Create new tables manually via SM203510 (Database Scripts) or the SQL Management Studio in Acumatica's cloud portal. Only ALTER TABLE ADD column statements execute via <Sql>.

Column already exists​

Fix: Always use IF NOT EXISTS guards in SQL:

IF NOT EXISTS (
  SELECT 1 FROM INFORMATION_SCHEMA.COLUMNS
  WHERE TABLE_NAME = 'POOrder' AND COLUMN_NAME = 'UsrExpArrivalDate'
)
ALTER TABLE POOrder ADD UsrExpArrivalDate datetime NULL

Session Issues​

Account lockout​

Cause: Too many concurrent API sessions exceeding the license limit.

Fix: AcuOps uses a Redis session gate (max 2 concurrent sessions). If locked out:

  1. Wait 15 minutes for auto-unlock, or
  2. Unlock manually in SM201010 (Users) → select user → clear lockout

Cause: .ASPXAUTH cookie has a 20-minute TTL.

Fix: AcuOps services refresh sessions proactively. If you see 401 errors in manual API calls, re-authenticate via /entity/auth/login.

Schema Verification​

Custom fields not appearing after publish​

Check these in order:

  1. Run GET /entity/default/24.200.001/{Entity}/$adHocSchema — if fields appear in custom.{Section}.{FieldName}, the publish succeeded
  2. If fields are missing, check the publish log for C# compilation errors
  3. Verify IsActive() returns true on all extension classes
  4. Confirm the project was included in the projectNames array during publish

custom: {} empty on record queries​

This is expected for list queries. Custom fields only appear:

  • On individual record GETs (not list queries with $top)
  • When the record has non-null values in those fields
  • Via $adHocSchema (always shows the schema, regardless of data)