Troubleshooting en Desarrollo AL
Guia de resolució d'errors comuns de desplegament, dependències i descàrregues de símbols en entorns Business Central.
En la nostra operativa DevSecOps, la majoria dels bloquejos no provenen d'errors de lògica en el nostre codi, sinó de fallades de configuració d'entorn, desfasaments de versions o problemes de comunicació de xarxa entre el nostre IDE local (VS Code) i el tenant al núvol.
Aquesta és la nostra base de coneixements per resoldre instantàniament els incidents registrats durant les fases de desenvolupament i integració.
Incident 1: Error 404 Not Found (Descàrrega de Símbols)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Símptoma
Sección titulada «Síntoma»Al ejecutar el comando AL: Download Symbols (o al intentar hacer Build con F5), la terminal (Output -> AL) devuelve bloques masivos de error similares a este:
[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.Diagnòstic Arrel (Sensibilitat de Versions)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»Este es un fallo de desincronización de versiones en el Manifiesto. Business Central es extremadamente estricto (version-sensitive). El error indica que nuestro archivo app.json local le está exigiendo al servidor que nos envíe las librerías del core en su versión 27.4.45366. Sin embargo, el Sandbox al que estamos apuntando (configurado en launch.json) tiene instalada una versión anterior (por ejemplo, la 25.0.0.0). Como el servidor no posee la versión que le exigimos, devuelve un 404.
Resolució Pas a Pas
Sección titulada «Resolución Paso a Paso»- Identificar la versión del servidor: Podemos comprobar la versión real entrando a la web de Business Central -> Ayuda y Soporte -> Acerca de.
- Relajar el app.json: Abrimos el archivo app.json en nuestro proyecto local.
- Rebajamos la versión mínima requerida. Modificamos "application" y "platform" a una versión que sepamos que es segura y universal (ej. 25.0.0.0).
- Rebajamos el motor de ejecución "runtime" a una versión compatible (ej. 13.0 o 16.0).
- Limpiar Caché: Borramos físicamente el contenido de la carpeta oculta .alpackages.
- Reintento: Ejecutamos de nuevo AL: Download Symbols. La terminal deberá mostrar All reference symbols have been downloaded.
Incident 2: Error per Dependències Fantasma (“API Reports”)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Símptoma
Sección titulada «Síntoma»Al intentar descargar símbolos o compilar, el sistema nos indica que falta una dependencia específica que no somos capaces de localizar, como por ejemplo: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Diagnòstic Arrel
Sección titulada «Diagnóstico Raíz»VS Code, al inicializar proyectos mediante AL: Go!, en ocasiones inyecta dependencias de módulos muy específicos (como módulos financieros avanzados) en el bloque "dependencies" del app.json. Si nuestro servidor Sandbox no tiene instalada esa App particular de Microsoft, el empaquetado global fallará en cadena.
Resolució
Sección titulada «Resolución»Hem de sanejar les dependències del nostre projecte.
- Abrimos app.json.
- Buscamos el array "dependencies": [ ... ].
- Si estamos desarrollando integraciones genéricas o APIs simples, eliminamos por completo los bloques de dependencias extrañas (como API Reports - Finance), dejando el array vacío [] o manteniendo únicamente las dependencias críticas de nuestra propia empresa.
- Borrar caché de .alpackages y volver a descargar símbolos.
Incident 3: Mite de les Carpetes i Nomenclatura (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Consulta/Dubte Freqüent
Sección titulada «Consulta/Duda Frecuente»Duda del equipo: “¿El compilador de AL falla si las carpetas raíz del proyecto en mi disco duro (ej. Consulta_Datos_Comercial) no están escritas en camelSensitive / CamelCase?”
Aclariment Tècnic DevSecOps
Sección titulada «Aclaración Técnica DevSecOps»La respuesta rotunda es NO. El compilador de AL no tiene sensibilidad a mayúsculas o formatos en los nombres físicos de las carpetas de Windows.
- SO File System: A Visual Studio Code y Windows les es indiferente si la ruta es C:/Proyectos/Consulta_Datos o c:/proyectos/cOnSuLtAdAtOs.
- Comportamiento del Compilador: Una vez que lanzamos la orden de compilación (Build), el motor empaqueta el contenido basándose exclusivamente en los metadatos declarados dentro del app.json (Propiedades "name" y "publisher"). El nombre de tu directorio local es ignorado e irrelevante para el servidor Cloud.
Recomendación de Nomenclatura: Nosotros utilizamos convención Snake_Case (guiones bajos) en los directorios (Entradas_Salidas_AL) estrictamente por legibilidad humana y orden visual en nuestros repositorios Git, no por imposición técnica del compilador.
4. Criteris d'Èxit de Triage
Sección titulada «4. Criterios de Éxito de Triage»- Limpieza: Vaciado preventivo de la carpeta .alpackages al realizar cambios estructurales en app.json.
- Validación: Coherencia absoluta en la suite de dependencias declaradas en el manifiesto con las extensiones instaladas en la nube.
- Seguimiento: Monitorización del canal de salida de “AL Language” de VS Code para el diagnóstico preciso de errores de red.

