直接コードデプロイのトラブルシューティング

Amazon Bedrock AgentCore ダイレクトコードデプロイを開始する際の一般的な問題と解決策。トラブルシューティングの詳細については、「Amazon Bedrock AgentCore ランタイムのトラブルシューティング」を参照してください。

AccessDenied: S3 アクセス許可が不十分

これが発生した場合: コンソール、SDK、または CLI 経由で S3 で zip アーティファクトを使用してエージェントを作成または更新中

これが発生する理由: Create/UpdateAgentRuntime の呼び出しに使用されるロールには、API 入力で渡された S3 URI に対する s3:GetObject アクセス許可がありません。

解決策: エージェントコアランタイムの作成/更新 API を呼び出すために使用されるロールに s3:GetObject アクセス許可を追加します。

{
"Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

AccessDenied: CMK で暗号化された S3 オブジェクトアクセス

これが発生した場合: 実行ロールに KMS 復号アクセス許可がない場合に、CMK で暗号化された S3 オブジェクトを使用してエージェントを作成するとき。

これが発生する理由: Create/UpdateAgentRuntime の呼び出しに使用されるロールには、エージェントコードを含む S3 オブジェクトの暗号化に使用される CMK に対する kms:Decrypt アクセス許可がありません。

解決策: 特定の CMK のロールに kms:Decrypt アクセス許可を追加します。

{
"Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": [
            "s3:GetObject",
            "kms:Decrypt"
        ],
        "Resource": [
            "arn:aws:s3:::your-bucket-name/*",
            "arn:aws:kms:us-west-2:your-account:key/your-cmk-key-id"
        ]
    }
  ]
}

CREATE_FAILED: コードパッケージの互換性

これが発生した場合: エージェントの作成中、または互換性のないコードパッケージ (間違ったアーキテクチャ、言語バージョン、またはパッケージ形式) で更新中。

これが発生する理由: アップロードされた ZIP ファイルには、誤ったアーキテクチャ (ARM64 と x86_64)、互換性のない言語バージョン、または AgentCore ランタイム要件に一致しない誤ったパッケージ構造用にコンパイルされたバイナリが含まれています。

解決策:

この問題を解決するには:

エラーインジケータ:

ARM64 バイナリ非互換性

これが発生した場合: エージェントの作成中に、非 non-ARM64 アーキテクチャ用にコンパイルされたネイティブバイナリが ZIP に含まれている場合。

これが発生する理由: AgentCore ランタイムは arm64 命令セットアーキテクチャのみをサポートします。このサービスは、デプロイパッケージ内のすべてのネイティブバイナリファイルをスキャンします。Python 用の .so ファイルと Node.js 用の .soと .node ファイルの両方をスキャンし、それらの ELF ヘッダーの ARM64 互換性を検証します。x86_64、macOS (Mach-O)、または別のアーキテクチャ用にバイナリがコンパイルされている場合、検証は失敗します。

解決策:

エラーインジケータ: "Your artifact contains binary files that are incompatible with Linux ARM64."

欠落しているエントリポイント

これが発生した場合: エージェントの作成中に、指定されたエントリポイントファイルが ZIP に存在しない場合。

これが発生する理由: entryPoint設定で指定したエントリポイントファイルパスが、デプロイパッケージのどのファイルとも一致しません。これは、ファイルが ZIP に含まれていない場合、パスのスペルが間違っている場合、または ZIP 構造が想定と異なる場合に発生する可能性があります。

解決策:

エラーインジケータ: "The specified entrypoint could not be found or accessed in your artifact."

Node.js 互換性のない engines.node 宣言

これが発生した場合: Node.js エージェントの作成中に、 package.jsonまたは共通の依存関係がターゲットの Node.js バージョンを除外するengines.node範囲を宣言した場合。

これが発生する理由: AgentCore Runtime は、ルートpackage.jsonと一般的な依存関係の engines.nodeフィールドをチェックします。バージョン範囲がターゲット Node.js バージョンを除外している場合 (Node.js 22 にデプロイ<18>=14 <18する場合など）、エージェントの作成は失敗します。

解決策:

エラーインジケータ: "Your artifact contains dependencies with engines.node declarations incompatible with the target Node.js version."

Node.js に OTEL パッケージがない

これが発生した場合: Node.js エージェントの作成中に、エントリポイントopentelemetry-instrumentで を指定しても、ADOT パッケージは ZIP に含まれません。

これが発生する理由: を使用する場合"entryPoint": ["opentelemetry-instrument", "app.js"]、AgentCore ランタイムは npm @aws/aws-distro-opentelemetry-node-autoinstrumentation パッケージがデプロイパッケージnode_modules/内に存在することを期待します。

解決策:

ZIP をパッケージ化する前に、ADOT パッケージをインストールします。

npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
zip -r deployment_package.zip app.js node_modules/ package.json

または、自動計測が必要ない場合は、エントリポイントからopentelemetry-instrumentプレフィックスを削除します。

エラーインジケータ: "OpenTelemetry instrumentation executable not found. The ZIP file requires open-telemetry dependencies, but none are present."