Ir al contenido

Troubleshooting en Desarrollo AL

Guía de resolución de errores comunes de despliegue, dependencias y descargas de símbolos en entornos Business Central.

0lecturas

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)»

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.

  1. Identificar la versión del servidor: Podemos comprobar la versión real entrando a la web de Business Central -> Ayuda y Soporte -> Acerca de.
  2. Relajar el app.json: Abrimos el archivo app.json en nuestro proyecto local.
  3. 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).
  4. Rebajamos el motor de ejecución "runtime" a una versión compatible (ej. 13.0 o 16.0).
  5. Limpiar Caché: Borramos físicamente el contenido de la carpeta oculta .alpackages.
  6. Reintento: Ejecutamos de nuevo AL: Download Symbols. La terminal deberá mostrar All reference symbols have been downloaded.

Incidente 2: Error por Dependencias Fantasma (“API Reports”)

Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»

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.

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.

Debemos sanear las dependencias de nuestro proyecto.

  1. Abrimos app.json.
  2. Buscamos el array "dependencies": [ ... ].
  3. 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.
  4. Borrar caché de .alpackages y 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)»

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

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.

  1. SO File System: A Visual Studio Code y Windows les es indiferente si la ruta es C:/Proyectos/Consulta_Datos o c:/proyectos/cOnSuLtAdAtOs.
  2. 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.

  • ✓ 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.