Acumatica 2026 R1: NullReferenceException on Customization Package Import

The Acumatica 2026 R1 release brought many enhancements, but it also introduced a significant regression affecting ISV solutions that rely on multi-package customization architectures. This case study examines a NullReferenceException that occurs during package import when a customization project contains ASPX page customizations for screens delivered by another package—a scenario that worked flawlessly in 2025 R2.

The Problem: A Silent Regression in 2026 R1

An ISV solution was split into three customization packages, published in a specific order:

On a clean 2026 R1 instance, uploading the FusionWMSOptimization package failed immediately with:

The project was never even created, making it impossible to reach the publishing stage. However, the workaround was straightforward: publish FusionWMSBasic and FusionWMSAdvanced first, and only then import FusionWMSOptimization.

Environment Details

• Fails on: Acumatica 2026 R1, build 26.100.0175
• Works on: Acumatica 2025 R2, build 25.201.0213

The Stack Trace

While the browser only displayed the generic error message, importing the exact same ZIP through the POST /CustomizationApi/Import endpoint returned the full trace:

System.NullReferenceException: Object reference not set to an instance of an object.
   at Customization.CstPageData.Save(XmlNode parent)
   at Customization.CstDocument.ExportXml(IObjectStorage src)
   at Customization.CstDocument.Copy(IObjectStorage src, IObjectStorage dest)
   at Customization.CstDbStorage.SaveDocument(CstDocument document, Boolean resetHash)
   at Customization.CstDbStorage.CreateNewProject(String name, Byte[] data, Nullable`1 level, String description)
   at Customization.CstWebsiteStorage.<ImportCustomizationProject>b__0(CustomizationResultData result)

The failure occurs inside CstPageData.Save—a <Page> item, representing a Classic UI ASPX customization—while the project is being re-serialized to be stored in the database.

The Cross-Package Dependency

The Optimization package contained <Page> (ASPX) customizations for six screens whose .aspx files it did not deliver—they were delivered by the Advanced package:

The pages that Optimization delivered itself (FR201000, FR300000, FR650794) imported without any problem, as did its customizations of stock screens (IN202500, IN204500, IN304000, SO301000, SO302000, SO501000).

Isolation Testing

To isolate the root cause, variants of the package were built, each keeping exactly one <Page> item and everything else intact:

Two critical controls were verified:

1. Identical bytes: The same ZIP, same content—it imports on 2025 R2 and throws on 2026 R1. This is not a migration issue.
2. Identical site state: Neither site had any customization published at the time. The base ASPX files were not present on either instance.

Root Cause Analysis

A <Page> item is a diff against an existing .aspx in the website. Based on the evidence, the root cause is clear:

• In 2025 R2: Importing a page diff whose base .aspx is not present in the site is tolerated. The item is stored as-is and only resolved at publish time.
• In 2026 R1: CstPageData.Save appears to try to resolve the diff against the base page while re-serializing the project into the database during import. The base page isn't there, something ends up null, and the entire import fails.

This represents a fundamental change in import behavior. Dependencies between packages that used to be implicit and only mattered at publish time have now become a hard failure at import time.

Solutions and Workarounds

1. The Immediate Workaround

Publish prerequisite packages first: Publish Basic and Advanced before importing Optimization. After that, the import succeeds normally.

This works because the base ASPX files are then present in the website when the dependent package tries to import.

2. Reorder Import Operations

For manual deployments, ensure packages are imported in the correct dependency order. This is similar to the standard practice for publishing packages.

3. CI/CD Pipeline Adjustments

For automated pipelines, modify the deployment process to:

1. Import Basic package
2. Publish Basic package
3. Import Advanced package
4. Publish Advanced package
5. Import Optimization package
6. Publish Optimization package

4. Review Package Architecture

Consider consolidating packages where possible. If the dependency is necessary, document the required import order clearly.

Preventive Measures for ISVs

Conclusion

The 2026 R1 release introduced a significant change in how Acumatica handles ASPX page customizations during package import. A NullReferenceException now occurs when a package attempts to customize a page whose base .aspx file is delivered by another package that hasn't been published yet.

This change transforms a previously implicit dependency into a hard failure at import time, with significant implications for ISVs shipping multi-package solutions and automated CI/CD pipelines.