AL開発におけるトラブルシューティング
Business Central環境でのデプロイ、依存関係、シンボルダウンロードの一般的なエラー解決ガイド
DevSecOps運用において、ほとんどのブロッカーはコードの論理エラーからではなく、環境構成の失敗、バージョンの不一致、またはローカルIDE(VS Code)とクラウドテナント間のネットワーク通信の問題から生じます。
これは、開発および統合フェーズ中に記録されたインシデントを即座に解決するための知識ベースです。
インシデント1: 404 Not Foundエラー(シンボルダウンロード)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»コマンド AL: Download Symbols を実行する(またはF5でビルドを試みる)と、ターミナル(出力 -> AL)はこのように多くのエラーを返します:
[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.根本原因の診断(バージョンの感度)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»これはマニフェストでのバージョンの不一致によるエラーです。Business Centralは非常に厳格(バージョンに敏感)です。エラーは、ローカルのファイル app.json がサーバーにコアのライブラリをバージョン 27.4.45366 で提供するよう要求していることを示しています。しかし、現在接続しているサンドボックス(launch.json で構成)には以前のバージョン(例: 25.0.0.0)がインストールされています。サーバーが要求されたバージョンを持っていないため、404エラーを返します。
ステップバイステップの解決策
Sección titulada «Resolución Paso a Paso»- サーバーのバージョンを識別する: Business Centralのウェブサイトにアクセスして、ヘルプとサポート -> についてから実際のバージョンを確認できます。
- app.jsonを緩和する: ローカルプロジェクトのファイル
app.jsonを開きます。 - 最小バージョン要件を低下させます。
"application"と"platform"を、安全で汎用的なバージョン(例:25.0.0.0)に変更します。 - 実行エンジンの
"runtime"を互換性のあるバージョン(例:13.0または16.0)に低下させます。 - キャッシュをクリーンアップする: 隠しフォルダ
.alpackagesの内容を物理的に削除します。 - 再試行:
AL: Download Symbolsを再度実行します。ターミナルにはAll reference symbols have been downloadedが表示されるはずです。
インシデント2: ファントム依存関係エラー(「API Reports」)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»シンボルをダウンロードしたりコンパイルしたりしようとすると、特定の依存関係が見つからないとシステムが表示されます。たとえば、A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found といったエラーです。
VS Codeで AL: Go! を使用してプロジェクトを初期化すると、特定のモジュール(例: 高度な財務モジュール)の依存関係が app.json の "dependencies" ブロックに自動的に挿入されることがあります。もしサンドボックスサーバーにそのMicrosoftのアプリがインストールされていない場合、グローバルパッケージングが失敗します。
プロジェクトの依存関係を整頓する必要があります。
app.jsonを開きます。"dependencies": [ ... ]の配列を探します。- 汎用的な統合やシンプルなAPIを開発している場合、
API Reports - Financeなどの不要な依存ブロックを完全に削除し、配列を空の[]にしたり、自社の重要な依存関係のみを保持します。 .alpackagesのキャッシュを削除し、再びシンボルをダウンロードします。
インシデント3: フォルダーと名前付けの誤解(CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»チームの疑問: 「ALコンパイラは、私のハードディスク上のプロジェクトのルートフォルダー(例: Consulta_Datos_Comercial)がcamelSensitive/CamelCaseで書かれていない場合に失敗しますか?」
DevSecOps技術的説明
Sección titulada «Aclaración Técnica DevSecOps»明確な答えはいいえです。ALコンパイラは、Windowsのフォルダ名の物理的な大文字小文字やフォーマットに敏感ではありません。
- SOファイルシステム: Visual Studio Code と Windows は、ルートが
C:/Proyectos/Consulta_Datosまたはc:/proyectos/cOnSuLtAdAtOsであるかどうかは気にしません。 - コンパイラの動作: ビルドコマンドを実行すると、エンジンは
app.json内のメタデータ("name"および"publisher"のプロパティ)にのみ基づいてコンテンツをパッケージ化します。ローカルディレクトリの名前はサーバーにとって無視され、関係ありません。
命名規則の推奨: 私たちは Git リポジトリでの人間の可読性と視覚的な整列を確保するため、ディレクトリで スネークケース(下線)を使用しています(例: Entradas_Salidas_AL)、コンパイラの技術的制約によるものではありません。
- ✓ クリーン:
app.jsonに構造的な変更を行う際、.alpackagesフォルダーを予防的に空にします。 - ✓ 検証: マニフェストに宣言された依存関係のサイクルとクラウドにインストールされている拡張機能の絶対的な整合性。
- ✓ 追跡: VS Code の「AL Language」チャネルの出力をモニタリングして、ネットワークエラーの正確な診断を行います。

