Dynamics 365 Business Central PTE Upload Error: Solving the Version String Mystery

Dynamics 365 Business Central developers know the specific pain of a rejected deployment operation right when you think you are ready to go live. There is nothing quite as frustrating as compiling your code successfully, generating the .app file without warnings, and then hitting a brick wall during the manual upload process via the Extension Management page.

Recently, a discussion surfaced in the community regarding a particularly stubborn error: Deploy Operation rejected. Error parsing version string. This issue specifically flagged the applicationDependencyVersion as the culprit. Even after the developer verified that their app.json dependencies matched the environment exactly, the error persisted across multiple sandboxes. If you are staring at your screen wondering why your Per-Tenant Extension (PTE) won’t upload, let’s break down what is likely happening and how to fix it.

Understanding the “Error Parsing Version String”

When you upload an extension to Dynamics 365 Business Central, the backend validation service reads your extension’s manifest (the app.json) and compares it against what is currently installed on the tenant.

The error message Error parsing version string usually suggests that the validation logic cannot interpret the version number provided in your dependencies. It isn’t necessarily saying the version is wrong (like trying to install v20 on a v19 server), but rather that the format or the reference is unintelligible to the deployment service.

The Common Culprits

If you are facing this issue, here is a checklist of what to investigate, moving beyond the basic “did you check the version number?” advice.

1. The Four-Segment Rule

Dynamics 365 Business Central relies on a strict semantic versioning format: Major.Minor.Build.Revision.

A common mistake occurs when a developer manually edits the app.json and inputs a three-segment version (e.g., 22.0.0) or introduces a typo. While the AL compiler in VS Code might be forgiving or assume a default revision of zero, the SaaS upload validator is often much stricter. Ensure that every dependency listed in your app.json explicitly uses the full four-segment format (e.g., 22.0.0.0).

2. The “Application” Property vs. Dependencies

In older versions of AL, we used the "application": "X.X.X.X" property in the app.json. In modern Dynamics 365 Business Central development, this property is largely deprecated in favor of listing the System Application and Base Application explicitly in the "dependencies" array.

If your file contains a lingering application property and a dependencies array, the validator might be choking on the conflict, especially if the versions differ slightly. The safest bet for modern PTEs is to remove the application property entirely and rely solely on the dependencies list.

3. ApplicationDependencyVersion Mismatch

The specific error mentioned in the community discussion pointed to applicationDependencyVersion. This internal property is generated when the .app file is packaged. It tells the server which version of the “Application” compilation target was used.

If you are developing against a Docker container or a local artifact that is slightly out of sync with the SaaS environment (even by a minor cumulative update), the symbols you downloaded might contain a version string that the SaaS environment doesn’t recognize or considers invalid.

The Fix:

1. Clear your local symbol cache.
2. Re-download symbols directly from the specific SaaS sandbox where you are trying to upload.
3. Recompile the package.

This ensures that the applicationDependencyVersion embedded in your package matches the exact platform version of the tenant.

Troubleshooting Workflow

If you are stuck in this loop, follow this step-by-step process to isolate the issue:

1. Validate JSON Syntax: Ensure your app.json does not contain hidden characters or malformed JSON that VS Code is ignoring but the server is catching.
2. Check Runtime Version: Verify that your "runtime" property in app.json is supported by the target Dynamics 365 Business Central version. Setting this too high (e.g., using runtime 11.0 on a v21 environment) usually gives a clear error, but it can sometimes manifest as parsing issues.
3. Minimal Dependencies: Try removing all non-essential dependencies. If you rely on 3rd party apps, ensure their version strings in your manifest exactly match what is installed on the tenant.
4. Re-package: Sometimes the .app file itself can be corrupted. Delete the file from your folder, run the build command again, and attempt the upload.

Summary

Deployment errors in Dynamics 365 Business Central are rarely random; they are usually just very specific about syntax. When the system says it cannot parse a version string, believe it. It usually means a version number is missing a segment, a deprecated property is interfering, or your local symbols are telling a different story than the SaaS environment. Double-check your app.json, enforce the four-digit version format, and ensure your symbols are fresh.