In this video, I show and talk about symbol creep. The phenomenon that happens when the .alpackages folder gets newer symbols files that what the app is targeted for.
In this video, Erik explains a common but often overlooked problem in AL development for Business Central that he calls “Symbol Creep” — the phenomenon where your AL packages folder accumulates symbol files from newer versions than your app is supposed to target, leading to compilation issues and deployment failures.
What Is Symbol Creep?
When building an AL app, developers tie their application to specific versions of the runtime and the Business Central application through the app.json file. This is meant to ensure the app will run on the versions you intend to support. However, despite these settings, developers frequently encounter unexpected compilation errors or deployment failures when customers try to install the app.
The root cause? The symbol files in your .alpackages folder don’t match the version you’re targeting.
A Practical Example
Erik demonstrates this using the Point of Sale app built on the channel in previous videos. The app was configured to target runtime 5.0 (Business Central version 16) to support on-premises customers running that version.
At some point, a developer adds a seemingly innocent page extension to the app. The code compiles without errors, the package is built, and it’s shipped off to version 16 customers. But then those customers report back: “Hey Erik, the Point of Sale app will not install.”
The error message says something about “Dimension Correction Schedule doesn’t exist” — and that’s correct, because the page being extended was introduced in version 18. The app compiled fine locally because the developer’s machine had version 18 symbols in the .alpackages folder.
How Does This Happen?
The AL compiler is, as Erik puts it, very “download happy.” Every time you deploy to a test sandbox or run Download Symbols, VS Code pulls down symbol files from whatever environment you’re connected to. If you’re running a Docker container with version 18, you get version 18 symbols — regardless of what your app.json says your target should be.
Over time, your .alpackages folder can accumulate a mix of symbols from different versions:
- Microsoft base application symbols from various versions
- Third-party app symbols (tax connectors, e-commerce integrations, etc.)
- System application symbols that don’t match your target runtime
Unless you’re carefully managing this folder, the symbols might not match what you think they should match.
Subtle Forms of Symbol Creep
The page extension example is an obvious case — the target page simply doesn’t exist in older versions. But Symbol Creep can be far more subtle. Erik highlights a great example: function overloads in the System Application.
Referencing a previous video where the team contributed a pull request to the System Application, they added overloads to the Base64Convert codeunit. After the change, the function had seven overloads. If a developer uses one of the newer overloads — say, the ToBase64 variant that accepts a TextEncoding parameter — the code compiles perfectly against the version 18 symbols sitting on their machine.
But when that code hits a build pipeline targeting version 16, or when a customer on an older version tries to install it, it breaks. The overload simply doesn’t exist in the older System Application.
How to Avoid Symbol Creep
The approach depends on how you manage your app development, but here are the key strategies:
- Control your symbols folder carefully. If your base version is 16, you should never have symbols newer than version 16 available in your
.alpackagesfolder during development. - Use a build pipeline with version-pinned symbols. Configure your CI/CD pipeline to download symbols specifically from version 16 (or whatever your minimum supported version is) at compilation time. This ensures the artifacts you’re compiling against are always the correct version — regardless of what individual developers have on their local machines.
- Be cautious with Download Symbols. Every time you run the command, check what version of symbols you’re pulling down. The AL Language extension will happily download symbols from whatever environment you’re connected to.
- Consider checking symbols into source control. Some teams check their symbol files into version control to ensure consistency across all developers. Others prefer to manage this through their build pipeline. Both approaches have merit.
- Reload your window after external changes. If you ever manipulate files in the
.alpackagesfolder outside of VS Code (copying, deleting, moving files), always reload the VS Code window. The AL compiler gets confused by external file system changes.
The Real-World Impact
Erik notes that he’s seen this issue frequently in the real world. ISVs send out app files that are supposed to work on version 16 or 17, and the app.json has all the correct version settings — but the app doesn’t install because something “crept in” from a newer version’s symbols. Without a build pipeline that does proper version-targeted compilation and testing, you might only discover the problem when a customer tries to install your app.
Conclusion
Symbol Creep is a real and common problem in AL development. It happens silently — your code compiles, your app.json looks correct, but your app is secretly dependent on symbols from a newer version than you intended to target. The fix is disciplined symbol management: pin your symbols to your minimum supported version, use build pipelines that enforce version correctness, and be vigilant about what’s sitting in your .alpackages folder. Taking these steps will make your apps far more predictable and save you from frustrating deployment failures.
