AcuOps Troubleshooting Guide¶

Common Errors¶

HTTP 404 or 405 on Import/Publish¶

Cause: Wrong HTTP method or URL casing.

Fix: - All Customization API endpoints require POST (not GET or PUT) - URLs are case-sensitive: /CustomizationApi/Import (capital C, capital I) - Correct: POST /CustomizationApi/Import - Wrong: PUT /CustomizationApi/import

Cause: Too many concurrent API sessions. Acumatica licenses limit concurrent sessions (typically 2-3).

Fix: - The deploy scripts auto-retry (5 attempts, 15s * attempt backoff) - Ensure previous sessions are properly logged out - Check for orphaned sessions in Acumatica: SM201030 (User Sessions) - If using multiple tools (MCP, sync workers), implement a session gate

NullReferenceException After Publish¶

Cause: <Table> elements in project.xml.

Fix: - Replace <Table> elements with <Sql> using ALTER TABLE:

<!-- BAD — causes NullReferenceException on cloud -->
<Table TableName="SOOrder">
  <Column ColumnName="UsrMyField" ... />
</Table>

<!-- GOOD — idempotent, CI/CD friendly -->
<Sql Name="AddUsrMyField">
  <CDATA name="AddUsrMyField.sql"><![CDATA[
IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID('SOOrder') AND name = 'UsrMyField')
    ALTER TABLE SOOrder ADD UsrMyField NVARCHAR(255) NULL
  ]]></CDATA>
</Sql>

CS0246: Type or Namespace Not Found¶

Cause: Referenced type doesn't exist or was moved in the target Acumatica version.

Common cases: | Type | Fix | |------|-----| | ARCustomerClass | Not public in v24.2. Use PX.Objects.AR.CustomerClass | | Moved namespaces | Check Acumatica release notes for namespace changes |

Diagnosis:

# Run strict validation to catch known problematic types
python scripts/validate-project.py --strict Customization/_project/project.xml

Publish Timeout¶

Cause: Large project or slow instance.

Fix: 1. Increase timeout in acuops.yaml:

publish:
  poll_timeout: 900  # 15 minutes

2. Check Acumatica System Monitor for publish progress 3. If consistently slow, check instance resources (CPU/RAM)

"Unknown tag SqlScript"¶

Cause: <SqlScript> elements are rejected by SM204505 import.

Fix: - Replace <SqlScript> with <Sql>:

<!-- BAD -->
<SqlScript Name="MyScript" Source="#CDATA">...</SqlScript>

<!-- GOOD -->
<Sql Name="MyScript">
  <CDATA name="MyScript.sql"><![CDATA[ ... ]]></CDATA>
</Sql>

Extension Missing IsActive() Method¶

Cause: All PXCacheExtension and PXGraphExtension classes require IsActive().

Fix:

public class MyExtension : PXCacheExtension<MyDAC>
{
    public static bool IsActive() => true;  // Add this
    // ...
}

Unbalanced Braces¶

Cause: Missing { or } in C# CDATA blocks.

Fix: - The validator reports the count: "Unbalanced braces — 12 open, 11 close" - Check for missing closing braces in event handlers, nested classes, or regions - Verify CDATA content wasn't truncated during export

Deploy Script: "yq not found"¶

Cause: yq YAML processor not installed.

Fix: - The script degrades gracefully — it uses CLI arguments and env vars instead - Install yq: brew install yq (macOS) or snap install yq (Linux) - In GitHub Actions, yq is available or can be installed via pip

Base64 Encoding Differences¶

Cause: macOS and Linux use different base64 flags.

The deploy scripts handle both automatically: - Linux: base64 -w0 (no line wrapping) - macOS: base64 -i (input file) with tr -d '\n'

Getting Help¶

Run validation with --strict for maximum diagnostics
Check Acumatica System Monitor for publish errors
Review GitHub Actions logs for the specific failure step
For API issues, the deploy scripts log HTTP status codes