Troubleshooting nello Sviluppo AL
Guida alla risoluzione degli errori comuni di deployment, dipendenze e download di simboli in ambienti Business Central.
Nella nostra operatività DevSecOps, la maggior parte dei blocchi non deriva da errori di logica nel nostro codice, ma da errori di configurazione dell'ambiente, discrepanze di versione o problemi di comunicazione di rete tra il nostro IDE locale (VS Code) e il tenant nel cloud.
Questa è la nostra base di conoscenza per risolvere istantaneamente gli incidenti registrati durante le fasi di sviluppo e integrazione.
Incidente 1: Errore 404 Not Found (Download dei Simboli)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Sintomo
Sección titulada «Síntoma»Eseguendo il comando AL: Download Symbols (o al provare a fare il Build con F5), il terminale (Output -> AL) restituisce blocchi massicci di errori simili a questo:
[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.Diagnosi alla Radice (Sensibilità delle Versioni)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»Questo è un errore di desincronizzazione delle versioni nel Manifesto. Business Central è estremamente rigoroso (version-sensitive). L'errore indica che il nostro file locale app.json sta richiedendo al server di inviarci le librerie del core nella versione 27.4.45366. Tuttavia, il Sandbox a cui stiamo puntando (configurato in launch.json) ha installata una versione precedente (ad esempio, la 25.0.0.0). Poiché il server non possiede la versione richiesta, restituisce un errore 404.
Risoluzione Passo dopo Passo
Sección titulada «Resolución Paso a Paso»- Identificare la versione del server: Possiamo verificare la versione reale accedendo al sito web di Business Central -> Aiuto e supporto -> Informazioni su.
- Allentare il
app.json: Apriamo il fileapp.jsonnel nostro progetto locale. - Abbiamo ridotto la versione minima richiesta. Modifichiamo
"application"e"platform"in una versione che sappiamo essere sicura e universale (es.25.0.0.0). - Abbiamo ridotto il motore di esecuzione
"runtime"a una versione compatibile (es.13.0o16.0). - Pulizia cache: Eliminiamo fisicamente il contenuto della cartella nascosta
.alpackages. - Riprova: Eseguiamo nuovamente
AL: Download Symbols. Il terminale dovrebbe mostrareAll reference symbols have been downloaded.
Incidente 2: Errore per Dipendenze Fantasma (“API Reports”)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Sintomo
Sección titulada «Síntoma»Nel tentativo di scaricare i simboli o compilare, il sistema indica che manca una dipendenza specifica che non siamo in grado di localizzare, come ad esempio: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Diagnosi alla Radice
Sección titulada «Diagnóstico Raíz»VS Code, inizializzando progetti tramite AL: Go!, a volte inietta dipendenze di moduli molto specifici (come moduli finanziari avanzati) nel blocco "dependencies" di app.json. Se il nostro server Sandbox non ha installata quella particolare App di Microsoft, il packaging globale fallirà a catena.
Risoluzione
Sección titulada «Resolución»Dobbiamo sanificare le dipendenze del nostro progetto.
- Apriamo
app.json. - Cerchiamo l'array
"dependencies": [ ... ]. - Se stiamo sviluppando integrazioni generiche o API semplici, eliminiamo completamente i blocchi di dipendenze estranee (come
API Reports - Finance), lasciando l'array vuoto[]o mantenendo esclusivamente le dipendenze critiche della nostra azienda. - Svuota la cache di
.alpackagese scarica nuovamente i simboli.
Incidente 3: Mito delle Cartelle e Nomenclatura (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Domanda/Dubbio Frequente
Sección titulada «Consulta/Duda Frecuente»Dubbio del team: “Il compilatore AL fallisce se le cartelle radice del progetto sul mio disco rigido (es. Consulta_Datos_Comercial) non sono scritte in camelSensitive / CamelCase?”
Chiarimento Tecnico DevSecOps
Sección titulada «Aclaración Técnica DevSecOps»La risposta è un NO categorico. Il compilatore AL non è sensibile alle maiuscole o ai formati nei nomi fisici delle cartelle di Windows.
- File System del SO: Per Visual Studio Code e Windows è indifferente se il percorso è
C:/Proyectos/Consulta_Datosoc:/proyectos/cOnSuLtAdAtOs. - Comportamento del compilatore: Una volta lanciato il comando di compilazione (Build), il motore impacchetta il contenuto basandosi esclusivamente sui metadati dichiarati all'interno di
app.json(Proprietà"name"e"publisher"). Il nome della tua directory locale viene ignorato ed è irrilevante per il server Cloud.
Raccomandazione di denominazione: Utilizziamo la convenzione Snake_Case (underscore) nelle directory (Entradas_Salidas_AL) strettamente per leggibilità umana e ordine visivo nei nostri repository Git, non per un'imposizione tecnica del compilatore.
4. Criteri di Successo del Triage
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Pulizia: Svuotamento preventivo della cartella
.alpackagesal effettuare modifiche strutturali inapp.json. - ✓ Validazione: Coerenza assoluta tra la suite di dipendenze dichiarate nel manifesto e le estensioni installate nel cloud.
- ✓ Monitoraggio: Monitoraggio del canale di output di “AL Language” di VS Code per una diagnostica precisa degli errori di rete.

