Ir al contenido

Troubleshooting en Desarrollo AL

Guia de resolução de erros comuns de despliegue, dependências e downloads de símbolos em entornos Business Central.

0lecturas

Na nossa operação DevSecOps, a maioria dos bloqueios não provém de erros de lógica no nosso código, mas sim de falhas de configuração de ambiente, desfasamentos de versões ou problemas de comunicação de rede entre o nosso IDE local (VS Code) e o tenant na nuvem.

Esta é a nossa base de conhecimentos para resolver instantaneamente os incidentes registados durante as fases de desenvolvimento e integração.

Incidente 1: Erro 404 Not Found (Download 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.

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 (por ejemplo, 25.0.0.0).
  4. Rebajamos el motor de ejecución "runtime" a una versión compatible (por ejemplo, 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: Erro por Dependências 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.

Devemos sanear as dependências do nosso projeto.

  1. Abrimos app.json.
  2. Buscamos o array "dependencies": [ ... ].
  3. Se estamos desenvolvendo integrações genéricas ou APIs simples, eliminamos por completo os blocos de dependências extrañas (como API Reports - Finance), deixando o array vazio [] ou mantendo apenas as dependências críticas de nossa própria empresa.
  4. Borrar caché de .alpackages e volver a descargar símbolos.

Incidente 3: Mito das Pastas e Nomenclatura (CamelCase vs Snake_case)

Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»

Duda do equipe: “O compilador de AL falha se as pastas raiz do projeto em meu disco rígido (por exemplo, Consulta_Dados_Comercial) não estão escritas em camelSensitive / CamelCase?”

A resposta rotunda é NO. O compilador de AL não tem sensibilidade a maiúsculas ou formatos em nomes físicos de pastas de Windows.

  1. SO File System: A Visual Studio Code e Windows são indiferentes se a rota é C:/Projetos/Consulta_Dados ou c:/projetos/cOnSuLtAdAtOs.
  2. Comportamento do Compilador: Uma vez que lançamos a ordem de compilação (Build), o motor embala o conteúdo com base exclusivamente em metadados declarados dentro do app.json (Propriedades "name" e "publisher"). O nome do seu diretório local é ignorado e irrelevante para o servidor Cloud.

Recomendação de Nomenclatura: Nós utilizamos convencção Snake_Case (guiones baixos) em pastas (Entradas_Salidas_AL) estrictamente por legibilidade humana e ordem visual em nossos repositórios Git, não por imposição técnica do 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.