AL compiler errors in Business Central

Every AL developer meets the same short list of compiler diagnostics, and most of them mean something other than what the message says. This reference covers the ones that consume the most time, in the order you tend to meet them: environment and symbol problems first, then the real code errors, then the warnings that become errors at the next release wave. Each entry is symptom, cause, fix, prevention. For the first-day setup problems around F5 and launch.json, see writing your first AL extension.

Symbols and dependencies

"You do not have the symbols for the referenced app" / nothing compiles

Symptom. Every object reference fails; the Problems pane fills with AL0118 and AL0185 for base-application types like Record Customer.

Cause. The .alpackages folder is empty or stale. Symbols are downloaded from the environment named in launch.json; if the environment name, server, or authentication is wrong, the download silently fails and the compiler has no base application to resolve against.

Fix. Check environmentName (sandbox name, exact case) and tenant in launch.json, sign in again, run AL: Download symbols, and confirm .alpackages now contains the Microsoft Application, Base Application, and System packages for your target version.

Prevention. Keep .alpackages out of Git and treat symbol download as part of environment setup. Pin application and platform in app.json to the version the sandbox actually runs.

AL0185: Table 'X' is missing

Symptom. A table that exists in the environment cannot be found by the compiler.

Cause. The table belongs to an app that is not in your dependencies in app.json, so its symbols are not loaded even if the app is installed. Also appears when a dependency's symbols were downloaded for a different version than the installed one.

Fix. Add the owning app (id, name, publisher, version) to dependencies, download symbols again, rebuild. For a Microsoft table, verify the application version in app.json is at least the version where the table was introduced.

Prevention. Declare dependencies before writing code against them; the compiler enforces the graph and it is cheaper to get right early. See AL extensions architecture.

Identifier and type errors

AL0118: The name 'X' does not exist in the current context

Symptom. An identifier — variable, field, procedure, object — is underlined and the build fails.

Cause. A typo, a variable declared in another procedure's var block, a field on a table you have not extended yet, a procedure that is local in another codeunit, or a missing dependency (see AL0185).

Fix. Check spelling and scope; declare the variable where it is used; add the table extension that creates the field; make the procedure non-local or move the call; add the dependency.

Prevention. Let IntelliSense drive identifier entry and keep the CodeCop analyzer on so naming is consistent.

AL0132: 'X' does not contain a definition for 'Y'

Symptom. A method or field is called on a record, codeunit, or interface that does not have it.

Cause. Wrong object — the method exists on a different codeunit, or the field is on the header not the line. Also the classic case after a wave: the method was renamed or removed and the obsolete warning was ignored.

Fix. Check the object's definition (F12 goes there); use the correct object or the replacement method named in the obsolete tag.

Prevention. Fix AL0432 warnings when they appear rather than when the object disappears.

AL0603: An implicit conversion is being performed from Text to Code

Symptom. A warning or error where a Text value is assigned to a Code field or variable.

Cause. Code fields are uppercase and length-limited; assigning arbitrary text can overflow at runtime. The compiler flags the implicit conversion.

Fix. Convert explicitly with CopyStr(TextValue, 1, MaxStrLen(CodeField)) and, where case matters, UpperCase. Consider whether the target should be Text in the first place.

Prevention. Use MaxStrLen on every assignment into a length-limited field; it is the difference between a compile-time nudge and a runtime "The length of the string is X, but it must be less than or equal to Y" error — see AL runtime errors.

AL0100: Syntax error, 'X' expected

Symptom. The compiler expected a token — usually ;, end, ) or begin — and found something else.

Cause. A missing semicolon, an unbalanced begin/end, or a stray character; the reported line is often one after the real mistake.

Fix. Look at the line above the reported one; format the document (Shift+Alt+F) to make block structure visible.

Prevention. Format on save and keep procedures short enough that block balance is obvious.

Scope and platform errors

AL0296: The application object or method 'X' has scope 'OnPrem' and cannot be used for 'Cloud' development

Symptom. Code that compiled against an on-premises target fails when target is Cloud.

Cause. The object or method is marked [Scope('OnPrem')] — .NET interop, file system access, certain system codeunits — and is not available in Business Central online.

Fix. Replace with the cloud-safe equivalent: Http and Json types instead of .NET, Azure Blob or SharePoint through the API instead of the file system, Isolated Storage instead of local secrets. Where no equivalent exists, the feature is on-premises-only by design.

Prevention. Set "target": "Cloud" in app.json from day one for anything that will ever run online.

"The object ID 5xxxx is not in the allowed range" / AL0223-class errors

Symptom. An object fails to compile because its ID falls outside the ranges the app declares.

Cause. idRanges in app.json does not cover the ID. Per-tenant extensions use 50000–99999; AppSource apps use their assigned range; a copied object often carries an ID from a different project.

Fix. Change the object ID to fall inside the declared range, or widen idRanges. If two installed apps declare the same IDs, one must move — the environment refuses to publish overlapping objects.

Prevention. Document your ID slice per app and per environment, and use the AL: Go! scaffold's range as a starting point rather than inventing one.

Warnings that become errors

AL0432: 'X' is marked for removal. Reason: … Tag: …

Symptom. A warning on a table, field, method, or event that still compiles.

Cause. The object is ObsoleteState = Pending. Microsoft removes obsolete objects after at least two release waves; when it does, AL0432 turns into AL0118 or AL0132 and the build breaks.

Fix. Read the reason and tag: it names the replacement. Migrate to it now, while the old one still exists to compare against.

Prevention. Treat AL0432 as an error in CI ("al.ruleSetPath" or the -errorLog gate in AL-Go for GitHub) and compile against the preview build six weeks before each wave — upgrading AL code across BC versions covers the rhythm.

AL0604: Use of implicit 'with' will be removed in the future. Qualify with 'Rec.'

Symptom. Warnings on every unqualified field reference inside a page or codeunit with a source table.

Cause. Legacy C/AL-style code relies on the implicit with on the source record. Microsoft is removing it because it makes field resolution ambiguous when tables change.

Fix. Qualify with Rec. (or the record variable name). Enable the NoImplicitWith feature in app.json so the compiler treats it as an error and finds every instance.

Prevention. Scaffold new projects with "features": ["NoImplicitWith"] and never write unqualified field access.

Analyzer findings that block AppSource

CodeCop, UICop, PerTenantExtensionCop, and AppSourceCop findings (rule IDs AA0xxx and AS0xxx) are not compiler errors, but AppSource validation treats many as blocking — missing affixes, non-unique captions, breaking schema changes, missing Access and Permissions properties. Turn the analyzers on in settings.json from the first commit; a warning during development costs seconds, the same finding at submission costs a resubmission cycle. Per-tenant extensions vs AppSource covers what validation checks.

When the build passes but publish fails

Two errors live between compiler and runtime. "The extension could not be published because it would cause a breaking schema change" means you deleted or narrowed a field that has shipped — mark it obsolete instead; schema removal breaks upgrade. "Object ID already in use" on publish means another installed extension — often an abandoned earlier attempt — claims the same ID; uninstall it from Extension Management or move your range. Runtime failures after a successful publish are a different reference: AL runtime errors in Business Central.