Troubleshooting při vývoji AL
Průvodce řešením běžných chyb při nasazování, závislostech a stahování symbolů v prostředích Business Central.
V naší operativě DevSecOps většina blokací nepochází z logických chyb v našem kódu, ale z chyb v konfiguraci prostředí, nesouladu verzí nebo problémů se síťovou komunikací mezi naším lokálním IDE (VS Code) a cloudovým tenantem.
Toto je naše znalostní báze pro okamžité řešení incidentů zaznamenaných během fází vývoje a integrace.
Incident 1: Chyba 404 Not Found (Stahování symbolů)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Příznak
Sección titulada «Síntoma»Při spuštění příkazu AL: Download Symbols (nebo při pokusu o Build pomocí F5) terminál (Output -> AL) vrátí masivní bloky chyb podobné tomuto:
[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.Kořenová diagnóza (Citlivost na verze)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»Toto je selhání synchronizace verzí v manifestu. Business Central je extrémně přísný (version-sensitive). Chyba indikuje, že náš lokální soubor app.json vyžaduje, aby server poslal knihovny jádra ve verzi 27.4.45366. Nicméně sandbox, na který poukazujeme (konfigurovaný v launch.json), má nainstalovanou předchozí verzi (například 25.0.0.0). Protože server nemá verzi, kterou požadujeme, vrátí 404.
Řešení krok za krokem
Sección titulada «Resolución Paso a Paso»- Identifikace verze serveru: Skutečnou verzi můžeme ověřit vstupem na web Business Central -> Nápověda a podpora -> O systému.
- Zmírnění
app.json: Otevřeme souborapp.jsonv našem lokálním projektu. - Snížíme minimální požadovanou verzi. Upravíme
"application"a"platform"na verzi, o které víme, že je bezpečná a univerzální (např.25.0.0.0). - Snížíme spustovací motor
"runtime"na kompatibilní verzi (např.13.0nebo16.0). - Vyčištění mecache: Fyzicky smažeme obsah skryté složky
.alpackages. - Znovný pokus: Znovu spustíme
AL: Download Symbols. Terminál by měl zobrazitAll reference symbols have been downloaded.
Incident 2: Chyba kvůli fantomovým závislostem („API Reports“)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Příznak
Sección titulada «Síntoma»Při pokusu o stažení symbolů nebo kompilaci nám systém indikuje chybějící specifickou závislost, kterou nejsme schopni lokalizovat, například: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Kořenová diagnóza
Sección titulada «Diagnóstico Raíz»VS Code při inicializaci projektů pomocí AL: Go! občas vkládá závislosti velmi specifických modulů (jako pokročilé finanční moduly) do bloku "dependencies" v app.json. Pokud náš Sandbox server nemá tuto konkrétní aplikaci Microsoftu nainstalovanou, globální balení selže řetězově.
Musíme vyčistit závislosti našeho projektu.
- Otevřeme
app.json. - Hledáme pole
"dependencies": [ ... ]. - Pokud vyvíjíme obecné integrace nebo jednoduchá API, zcela odstraníme bloky neobvyklých závislostí (jako
API Reports - Finance) a necháme pole[]prázdné nebo si ponecháme pouze kritické závislosti naší vlastní společnosti. - Vymazat mezipaměť
.alpackagesa znovu stáhnout symboly.
Incident 3: Mýtus o složkách a názvosloví (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Častý dotaz/pochybnost
Sección titulada «Consulta/Duda Frecuente»Dotaz týmu: „Selže AL kompilátor, pokud kořenové složky projektu na mém disku (např. Consulta_Datos_Comercial) nejsou napsány ve formátu camelSensitive / CamelCase?“
Technické objasnění DevSecOps
Sección titulada «Aclaración Técnica DevSecOps»Jednoznačná odpověď zní NE. AL kompilátor není citlivý na velikost písmen ani na formát fyzických názvů složek ve Windows.
- Souborový systém OS: Pro Visual Studio Code i Windows je jedno, zda je cesta
C:/Proyectos/Consulta_Datosneboc:/proyectos/cOnSuLtAdAtOs. - Chování kompilátoru: Jakmile spustíme příkaz pro sestavení (Build), engine balí obsah výhradně na základě metadat deklarovaných v
app.json(Vlastnosti"name"a"publisher"). Název vašeho lokálního adresáře je ignorován a pro cloudový server je irelevantní.
Doporučení pro pojmenovávání: V adresářích (Entradas_Salidas_AL) používáme konvenci Snake_Case (podtržítka) striktně kvůli lidské čitelnosti a vizuálnímu řádu v našich Git repozitářích, nikoliv z technického vynucení kompilátoru.
4. Kritéria úspěšnosti triáže
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Vyčištění: Preventivní vyčištění složky
.alpackagespři provádění strukturálních změn vapp.json. - ✓ Ověření: Absolutní koherence v sadě závislostí deklarovaných v manifestu s nainstalovanými rozšířeními v cloudu.
- ✓ Sledování: Monitorování výstupního kanálu „AL Language“ ve VS Code pro přesnou diagnostiku chyb sítě.

