Fehlerbehebung in der AL-Entwicklung
Leitfaden zur Behebung häufiger Fehler bei der Bereitstellung, bei Abhängigkeiten und beim Herunterladen von Symbolen in Business Central-Umgebungen.
In unserem DevSecOps-Betrieb stammen die meisten Blockaden nicht von Logikfehlern in unserem Code, sondern von Fehlern in der Umgebungskonfiguration, Versionskonflikten oder Netzwerkkommunikationsproblemen zwischen unserer lokalen IDE (VS Code) und dem Cloud-Tenant.
Dies ist unsere Wissensdatenbank zur sofortigen Behebung von Vorfällen, die während der Entwicklungs- und Integrationsphasen registriert wurden.
Vorfall 1: Fehler 404 Not Found (Symbol-Download)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Symptom
Sección titulada «Síntoma»Beim Ausführen des Befehls AL: Download Symbols (oder beim Versuch, einen Build mit F5 durchzuführen) gibt das Terminal (Output -> AL) massive Fehlerblöcke zurück, die diesem hier ähneln:
[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.Ursachendiagnose (Versionsempfindlichkeit)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»Dies ist ein Versionsdesynchronisierungsfehler im Manifest. Business Central ist extrem streng (versionsempfindlich). Der Fehler weist darauf hin, dass unsere lokale Datei app.json vom Server verlangt, die Core-Bibliotheken in ihrer Version 27.4.45366 zu senden. Der Sandbox-Server, auf den wir zeigen (konfiguriert in launch.json), hat jedoch eine frühere Version installiert (z. B. 25.0.0.0). Da der Server die von uns geforderte Version nicht besitzt, gibt er einen 404 zurück.
Schritt-für-Schritt-Lösung
Sección titulada «Resolución Paso a Paso»- Serverversion identifizieren: Wir können die tatsächliche Version überprüfen, indem wir die Business Central Webseite aufrufen -> Hilfe und Support -> Über.
app.jsonlockern: Wir öffnen die Dateiapp.jsonin unserem lokalen Projekt.- Wir senken die erforderliche Mindestversion. Wir ändern
"application"und"platform"auf eine Version, von der wir wissen, dass sie sicher und universell ist (z. B.25.0.0.0). - Wir führen ein Downgrade der Execution Engine
"runtime"auf eine kompatible Version durch (z. B.13.0oder16.0). - Cache leeren: Wir löschen den Inhalt des versteckten Ordners
.alpackagesphysisch. - Wiederholung: Wir führen
AL: Download Symbolserneut aus. Das Terminal sollteAll reference symbols have been downloadedanzeigen.
Vorfall 2: Fehler durch Phantom-Abhängigkeiten („API Reports“)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Symptom
Sección titulada «Síntoma»Beim Versuch, Symbole herunterzuladen oder zu kompilieren, zeigt das System an, dass eine spezifische Abhängigkeit fehlt, die wir nicht lokalisieren können, wie zum Beispiel: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Ursachendiagnose
Sección titulada «Diagnóstico Raíz»VS Code injiziert bei der Initialisierung von Projekten über AL: Go! gelegentlich Abhängigkeiten von sehr spezifischen Modulen (wie fortgeschrittene Finanzmodule) in den Block "dependencies" von app.json. Wenn unser Sandbox-Server diese spezielle Microsoft-App nicht installiert hat, wird die globale Paketierung in einer Kettenreaktion fehlschlagen.
Wir müssen die Abhängigkeiten unseres Projekts bereinigen.
- Wir öffnen
app.json. - Wir suchen das Array
"dependencies": [ ... ]. - Wenn wir generische Integrationen oder einfache APIs entwickeln, entfernen wir Fremdabhängigkeiten (wie
API Reports - Finance) vollständig, sodass das Array leer bleibt[]oder nur die kritischen Abhängigkeiten unseres eigenen Unternehmens beibehalten werden. - Cache von
.alpackageslöschen und Symbole erneut herunterladen.
Vorfall 3: Mythos der Ordner und Nomenklatur (CamelCase vs. Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Häufige Frage/Zweifel
Sección titulada «Consulta/Duda Frecuente»Teamfrage: „Schlägt der AL-Compiler fehl, wenn die Stammordner des Projekts auf meiner Festplatte (z. B. Consulta_Datos_Comercial) nicht in camelSensitive / CamelCase geschrieben sind?“
Technische Klarstellung zu DevSecOps
Sección titulada «Aclaración Técnica DevSecOps»Die eindeutige Antwort lautet NEIN. Der AL-Compiler unterscheidet nicht zwischen Groß- und Kleinschreibung oder Formaten bei den physischen Windows-Ordnernamen.
- Betriebssystem-Dateisystem: Visual Studio Code und Windows sind es egal, ob der Pfad
C:/Proyectos/Consulta_Datosoderc:/proyectos/cOnSuLtAdAtOslautet. - Verhalten des Compilers: Sobald wir den Build-Befehl ausführen, verpackt die Engine den Inhalt ausschließlich basierend auf den innerhalb von
app.jsondeklarierten Metadaten (Eigenschaften"name"und"publisher"). Der Name deines lokalen Verzeichnisses wird ignoriert und ist für den Cloud-Server irrelevant.
Benennungsempfehlung: Wir verwenden in den Verzeichnissen (Entradas_Salidas_AL) die Snake_Case-Konvention (Unterstriche) ausschließlich aus Gründen der menschlichen Lesbarkeit und visuellen Ordnung in unseren Git-Repositories, nicht aufgrund einer technischen Vorgabe des Compilers.
4. Triage-Erfolgskriterien
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Reinigung: Vorbeugendes Leeren des Ordners
.alpackagesbeim Durchführen struktureller Änderungen anapp.json. - ✓ Validierung: Absolute Konsistenz der im Manifest deklarierten Abhängigkeitssuite mit den in der Cloud installierten Erweiterungen.
- ✓ Verfolgung: Überwachung des Ausgabe-Kanals von „AL Language“ von VS Code für die präzise Diagnose von Netzwerkfehlern.

