Troubleshooting in AL Development
Guide for resolving common deployment errors, dependencies, and symbol downloads in Business Central environments.
In our DevSecOps operations, most blockers do not stem from logic errors in our code, but from environment configuration failures, version mismatches, or network communication issues between our local IDE (VS Code) and the cloud tenant.
This is our knowledge base to instantly resolve incidents recorded during the development and integration phases.
Incident 1: 404 Not Found Error (Symbol Download)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Symptom
Sección titulada «Síntoma»When running the command AL: Download Symbols (or when attempting to Build with F5), the terminal (Output -> AL) returns massive error blocks similar to this:
[2026-03-24 10:15:23] Sending request to https://api.businesscentral.../v2.0/sandbox/dev/packages?publisher=Microsoft&appName=Application&versionText=27.4.45366[2026-03-24 10:15:24] Error: Not Found[2026-03-24 10:15:24] The request for path ... failed with code NotFound.error AL1022: A package with publisher 'Microsoft', name 'Application', and a version compatible with '27.4.45366' could not be found.Root Cause Diagnosis (Version Sensitivity)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»This is a version desynchronization failure in the Manifest. Business Central is extremely strict (version-sensitive). The error indicates that our local app.json file is requiring the server to send us the core libraries in version 27.4.45366. However, the Sandbox we are pointing to (configured in launch.json) has an older version installed (for example, 25.0.0.0). Since the server does not have the version we are demanding, it returns a 404.
Step-by-Step Resolution
Sección titulada «Resolución Paso a Paso»- Identify the server version: We can check the actual version by going to the Business Central web portal -> Help & Support -> About.
- Relax the
app.json: We open theapp.jsonfile in our local project. - We lower the minimum required version. We modify
"application"and"platform"to a version that we know is safe and universal (e.g.,25.0.0.0). - We downgrade the
"runtime"runtime engine to a compatible version (e.g.,13.0or16.0). - Clear Cache: We physically delete the contents of the hidden
.alpackagesfolder. - Retry: We run
AL: Download Symbolsagain. The terminal should showAll reference symbols have been downloaded.
Incident 2: Error due to Ghost Dependencies (“API Reports”)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Symptom
Sección titulada «Síntoma»When attempting to download symbols or compile, the system indicates that a specific dependency is missing that we are unable to locate, such as: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Root Cause Diagnosis
Sección titulada «Diagnóstico Raíz»VS Code, when initializing projects via AL: Go!, occasionally injects very specific module dependencies (such as advanced financial modules) into the "dependencies" block of app.json. If our Sandbox server does not have that particular Microsoft App installed, the global packaging will fail in a chain reaction.
Resolution
Sección titulada «Resolución»We must sanitize our project's dependencies.
- We open
app.json. - We look for the
"dependencies": [ ... ]array. - If we are developing generic integrations or simple APIs, we completely remove the strange dependency blocks (such as
API Reports - Finance), leaving the array empty[]or maintaining only our company's critical dependencies. - Clear the cache of
.alpackagesand re-download symbols.
Incident 3: The Myth of Folders and Naming Conventions (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»FAQ / Common Question
Sección titulada «Consulta/Duda Frecuente»Team question: “Does the AL compiler fail if the project's root folders on my hard drive (e.g., Consulta_Datos_Comercial) are not written in camelSensitive / CamelCase?”
DevSecOps Technical Clarification
Sección titulada «Aclaración Técnica DevSecOps»The resounding answer is NO. The AL compiler is not case-sensitive or format-sensitive regarding the physical names of Windows folders.
- OS File System: Visual Studio Code and Windows are indifferent to whether the path is
C:/Proyectos/Consulta_Datosorc:/proyectos/cOnSuLtAdAtOs. - Compiler Behavior: Once the build command is launched, the engine packages the content based exclusively on the metadata declared within the
app.json(Properties"name"and"publisher"). Your local directory name is ignored and irrelevant to the Cloud server.
Naming Convention Recommendation: We use Snake_Case convention (underscores) in directories (Entradas_Salidas_AL) strictly for human readability and visual order in our Git repositories, not due to technical imposition by the compiler.
4. Triage Success Criteria
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Cleanup: Preventive emptying of the
.alpackagesfolder when making structural changes inapp.json. - ✓ Validation: Absolute coherence between the dependency suite declared in the manifest and the extensions installed in the cloud.
- ✓ Monitoring: Monitoring the VS Code “AL Language” output channel for precise network error diagnosis.

