Incompatible PTE Extension Warning before

Business Central Upgrade

1. Overview

When Microsoft releases a new version of Business Central, it sometimes introduces breaking changes that affect custom Per-Tenant Extensions (PTEs). A PTE is any custom extension installed in your environment that is not part of the standard Business Central or Sparkrock 365 base application.

Before proceeding with an upgrade, Business Central validates all installed extensions against the target version. If a PTE references a feature, codeunit, or API that has been removed or changed in the new version, the upgrade is blocked and you receive a notification like the one below.

The validation result message tells you which source file in the extension contains the problem and what is missing or incompatible. This information is intended for the extension developer — you do not need to interpret or fix it yourself. Simply note the Extension name and pass the full notification to Sparkrock support.

2. Do You Need to Act?

Most customers do not need to take any action themselves. Microsoft sends these notifications in advance as a heads-up, not as an urgent demand for immediate action.

Use the table below to determine the right path for your situation:

3. Resolving the Incompatibility Yourself

If Sparkrock does not have access to your environment and you need to resolve the incompatibility before the upgrade, follow the steps below.

Step 1 — Identify the Incompatible Extension

1. Open the notification email or message from Microsoft and note the exact Extension name and Extension ID shown. You will use this to locate the extension in your environment.
2. Log in to your Business Central environment as a user with the System Administrator or Extension Management role.

Step 2 — Uninstall the Extension

1. Use the search bar (Alt+Q) and type Extension Management, then open the page.
2. In the search box on the page, type the name of the incompatible extension to filter the list.
3. Click on the extension to select it, then click Manage → Uninstall from the action bar.
4. In the uninstall dialog, choose whether to delete extension data. In most cases, leave this option off to preserve your existing data for reinstallation after the upgrade.
5. Confirm the uninstall. The extension will be removed from your environment.

Step 3 — Proceed with the Upgrade

1. Return to the upgrade process in Business Central or Microsoft’s admin portal and run the upgrade again.
2. Business Central will re-validate all installed extensions against the new version. With the incompatible extension removed, the upgrade should proceed successfully.

Step 4 — Reinstall the Updated Extension

1. Once the upgrade is complete, contact Sparkrock to obtain the updated, compatible version of the extension built against the new Business Central version.
2. Install the new version via Extension Management → Manage → Upload Extension, or Sparkrock will deploy it directly if access is available.
3. Verify that the extension is functioning correctly by testing the affected functionality in your environment.

4. What Are Breaking Changes?

With each new Business Central version, Microsoft may remove, rename, or restructure internal features, codeunits, and APIs. These are called breaking changes because any extension that depends on the old functionality will stop working when the new version is installed.

Common examples of breaking changes include:

• A codeunit or function that the extension calls has been removed or renamed by Microsoft.
• A table or field that the extension references has been deprecated.
• A standard page or report the extension extends has been restructured.

These changes are made by Microsoft as part of the ongoing evolution of the Business Central platform and are outside of Sparkrock’s control. When a breaking change affects a custom extension, the extension must be updated by its developer — Sparkrock or the original PTE author — to use the new or replacement functionality before it can be reinstalled on the upgraded environment.

5. Summary

• You likely do not need to act immediately. Microsoft sends these notifications in advance to allow time to prepare.
• If Sparkrock has access to your environment, submit a support ticket and we will handle the entire process.
• If you need to act yourself: uninstall the incompatible extension → run the upgrade → reinstall the updated version provided by Sparkrock.
• Breaking changes are a normal part of Business Central upgrades. The extension must be updated by its developer and recompiled against the new BC version — this cannot be resolved by the customer alone.