Ir al contenido

Troubleshooting in AL Development

Guide for resolving common deployment errors, dependencies, and symbol downloads in Business Central environments.

0views

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.

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.

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.

  1. Identify the server version: We can check the actual version by going to the Business Central web portal -> Help & Support -> About.
  2. Relax the app.json: We open the app.json file in our local project.
  3. 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).
  4. We downgrade the "runtime" runtime engine to a compatible version (e.g., 13.0 or 16.0).
  5. Clear Cache: We physically delete the contents of the hidden .alpackages folder.
  6. Retry: We run AL: Download Symbols again. The terminal should show All 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”)»

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.

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.

We must sanitize our project's dependencies.

  1. We open app.json.
  2. We look for the "dependencies": [ ... ] array.
  3. 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.
  4. Clear the cache of .alpackages and 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)»

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?”

The resounding answer is NO. The AL compiler is not case-sensitive or format-sensitive regarding the physical names of Windows folders.

  1. OS File System: Visual Studio Code and Windows are indifferent to whether the path is C:/Proyectos/Consulta_Datos or c:/proyectos/cOnSuLtAdAtOs.
  2. 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.

  • ✓ Cleanup: Preventive emptying of the .alpackages folder when making structural changes in app.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.