Why Business Central Apps Fail AppSource Validation, and How to Get Through It

What does Microsoft check when a Business Central app is submitted?

Microsoft's technical validation checklist lists the mandatory requirements and describes the automated validation in detail, so read it first and treat it as the authority. In short, the manifest is checked for mandatory properties, the publisher's affix registration and the package signature are verified, the name, publisher and version are compared with the offer, and runtime packages are rejected. Then, for every country or region and every release from the computed minimum release to the current one, dependencies are resolved, the app is compiled, and AppSourceCop runs against the previous versions as baselines. Any unresolved dependency, compilation error, violation or breaking change rejects the submission.

That structure explains why validation fails on things a working app never shows in testing: the app runs fine in your sandbox, but it is checked against releases, countries and earlier versions you did not test.

Why do affix and object ID range problems block a submission?

Two registrations happen outside the code, which is why they are easy to miss. Your publisher name must have registered affixes, and the extension must use them; and the object ID range must be registered for the publisher and used in the app. If the publisher name has no registered affixes, the submission is rejected before any code is analysed. Inside the code, AppSourceCop enforces the same rules: AppSourceCop rule AS0011 requires an affix, AS0054 requires the affixes to be declared in AppSourceCop.json, and AS0013, AS0014 and AS0084 check that field and object IDs sit in the allocated range.

• Confirm the affixes are registered against the exact publisher name in app.json, not a trading name.
• Declare them in mandatoryAffixes in AppSourceCop.json so the analyzer checks every new object, extension object and field.
• Check idRanges in app.json against the registered range, including objects added late by a second developer.
• Apply the affix to procedures added in extension objects as well; AS0079 warns when they are missing.

Why does AppSourceCop fail on breaking changes against the previous version?

Because validation compares your new package with what is already published, and most teams never run that comparison locally. AppSourceCop finds the previous version through the name, publisher and version settings in AppSourceCop.json, looking for that package in the folder set by baselinePackageCachePath, or the project's package cache if that is not set. If it cannot find it, rule AS0003 reports that the previous version could not be found.

With the baseline in place, the upgrade rules catch what would break customers or dependent extensions: deleted tables and fields (AS0001, AS0002), renamed or retyped fields (AS0004, AS0005), changed keys (AS0009, AS0010), removed public procedures or event attributes (AS0018, AS0019), changed event and external procedure signatures (AS0024 to AS0026), and deleted pages, actions or controls (AS0029, AS0031, AS0032). The fix is not to suppress the rule but to obsolete properly: mark the element ObsoleteState Pending in one version and remove it in a later one. If you submit a version that is not the latest, Microsoft also tests the next published version against it, so an old hotfix can fail for changes made after it.

What goes wrong with translation files and permission sets?

Translation files are mandatory: the checklist requires the extension to use them, and AppSourceCop rule AS0015 fails the build when the TranslationFile feature is not enabled in app.json. With the feature on, the compiler generates the XLIFF file from every caption, label and tooltip, and translated XLIFF files are added for the languages you support. Keep the translation IDs stable between versions; AS0125 reports changed XLIFF IDs.

Permission sets fail validation in a quieter way. Microsoft requires the extension to create its own permission sets, and a user must not need SUPER to set up and use the app. Define them as AL permissionset objects rather than XML files (AS0094 warns on XML), make sure every table has a matching permission set (AS0103), and avoid permission set extensions that grant rights on other publishers' objects or use wildcards (AS0110 to AS0113).

Why do install and upgrade codeunits matter for validation?

The checklist requires upgrade code that lets the app upgrade from version to version, and it requires you to publish, sync, install, uninstall and reinstall the extension in a Business Central environment before submitting. Install codeunits set up default data when the app is first installed in a company; upgrade codeunits move or transform data when a new version replaces an old one. An app without them often installs cleanly in a fresh sandbox and fails the first time it meets real data from the previous version.

• Use an install codeunit for setup records, so a new company gets a working configuration.
• Use an upgrade codeunit, guarded by upgrade tags, for every schema or data change between versions.
• Set DataClassification on every field to a value other than ToBeClassified; AS0016 is an error.
• Do not subscribe to OnBeforeCompanyOpen or OnAfterCompanyOpen; AS0061 is an error and the checklist names the replacements.
• Test the upgrade with data from the previous version, not only a clean install.

Which dependency problems stop a submission?

Every dependency must resolve for every country and release you target, or the submission is rejected. Dependencies that are already on Marketplace for those countries are downloaded automatically; you only include a dependency in your submission when you are shipping a newer version of it. Two patterns cause most rejections: a dependency on an app that is not available on Marketplace in the targeted countries, such as a per-tenant extension or an internal library, and including extensions created by Microsoft in the submission, which Microsoft rejects. Marketplace apps must also use the application property in app.json instead of explicit dependencies on the Base Application and System Application (AS0085, AS0100), and that property sets the minimum release the app is validated against and becomes available from.

Why do offer listing and package mismatches cause rejections?

The package and the Partner Center offer are checked against each other, and a mismatch rejects the submission before any code runs. These are the cheapest failures to avoid, and the most frustrating to hit after a long build.

• The name, publisher and version in app.json must match the values in the offer description.
• The .app file must be digitally signed with a valid certificate.
• The package must not be a runtime package.
• The AppId must be unique; the same AppId cannot be used for a per-tenant extension and a Marketplace app.
• Keep the countries and languages in the offer consistent with supportedCountries in AppSourceCop.json and the translations in the package.

How do you run the same validation yourself before submitting?

Microsoft documents a way to run the same checks locally. The Run-AlValidation command in the BcContainerHelper PowerShell module takes your previous app files, the new app files, the countries to validate against, your affixes and your supported countries, and runs AppSourceCop for each country, surfacing publishing and install or upgrade errors as exceptions. It needs Docker and a machine that can run Business Central containers, and Microsoft recommends wiring it into a DevOps pipeline, for example with AL-Go for GitHub. Note that it cannot see whether your affixes are actually registered with Microsoft.

When a submission still fails, the detailed results are sent to the Azure Application Insights resource named in the applicationInsightsConnectionString property of the main extension's app.json. Set that property before you submit, not after the first rejection.

When does it make sense to bring in outside AL capacity?

When the app works but the release does not: baselines were never set up, obsoletion was skipped, upgrade code is missing, or the team that built version one has moved on. Solzet's own AL developers build Business Central apps, fix validation blockers, add the missing upgrade and permission work, and set up the validation pipeline, with your company staying the publisher in Partner Center. The commercial side of that work is on our Business Central AL development page. Microsoft partners and ISVs that need the capacity under their own brand can use our white-label subcontracting.