Troubleshooting en Desarrollo AL
Guía de resolución de errores comunes de despliegue, dependencias y descargas de símbolos en entornos Business Central.
En nuestra operativa DevSecOps, la mayoría de los bloqueos no provienen de errores de lógica en nuestro código, sino de fallos de configuración de entorno, desfases de versiones o problemas de comunicación de red entre nuestro IDE local (VS Code) y el tenant en la nube.
Esta es nuestra base de conocimientos para solventar instantáneamente los incidentes registrados durante las fases de desarrollo e integración.
Incidente 1: Error 404 Not Found (Descarga de Símbolos)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Síntoma
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óstico Raíz (Sensibilidad de Versiones)
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ón Paso a Paso
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 archivoapp.jsonen 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.0o16.0). - Limpiar Caché: Borramos físicamente el contenido de la carpeta oculta
.alpackages. - Reintento: Ejecutamos de nuevo
AL: Download Symbols. La terminal deberá mostrarAll reference symbols have been downloaded.
Incidente 2: Error por Dependencias Fantasma (“API Reports”)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Síntoma
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óstico Raíz
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ón
Sección titulada «Resolución»Debemos sanear las dependencias de nuestro proyecto.
- 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
.alpackagesy volver a descargar símbolos.
Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Consulta/Duda Frecuente
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?”
Aclaración Técnica 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_Datosoc:/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. Criterios de Éxito de Triage
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Limpieza: Vaciado preventivo de la carpeta
.alpackagesal realizar cambios estructurales enapp.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.

