View a markdown version of this page

對直接程式碼部署進行故障診斷 - Amazon Bedrock AgentCore
AccessDenied：S3 許可不足AccessDenied：CMK 加密的 S3 物件存取CREATE_FAILED：程式碼套件相容性ARM64 二進位不相容缺少進入點Node.js 不相容的 engine.node 宣告Node.js 缺少 OTEL 套件

對直接程式碼部署進行故障診斷

開始使用 Amazon Bedrock AgentCore 直接程式碼部署時的常見問題和解決方案。如需更多故障診斷資訊，請參閱故障診斷 Amazon Bedrock AgentCore 執行期。

AccessDenied：S3 許可不足

發生這種情況時：在透過主控台、 SDK 或 CLI 在 S3 中使用壓縮成品建立或更新代理程式期間

發生這種情況的原因：用於呼叫 Create/UpdateAgentRuntime 的角色在 API 輸入中傳遞的 S3 uri 上沒有 s3：GetObject 許可。

解決方案：在用於呼叫 Agentcore 執行期建立/更新 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 許可。

解決方案：將 kms:Decrypt 許可新增至特定 CMK 的角色：

{
"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 執行期需求的不正確套件結構所編譯的二進位檔。

解決方案：

若要解決此問題：

  1. 確保為 arm64 編譯程式碼。

  2. 使用相容的語言版本 （檢查 AgentCore Runtime 支援的版本）。

  3. 驗證 ZIP 結構包含適當的進入點和相依性。

  4. 在相容的執行期環境中重建套件。

錯誤指標：

  • 代理程式狀態：CREATE_FAILED 或執行時間錯誤

  • 在 cloudwatch 日誌中匯入錯誤或「無法執行二進位檔案」訊息

  • 當您執行 getAgentRuntimeEndpoint 時，架構不符錯誤。

ARM64 二進位不相容

發生這種情況時：在建立代理程式期間，當您的 ZIP 包含為non-ARM64 架構編譯的原生二進位檔時。

發生這種情況的原因：AgentCore 執行期僅支援 arm64 指令集架構。服務會掃描部署套件中的所有原生二進位檔案：.soPython 檔案.so和 Node.js .node 檔案，並驗證其 ELF 標頭的 ARM64 相容性。如果針對 x86_64、macOS (Mach-O) 或其他架構編譯任何二進位檔，則驗證會失敗。

解決方案：

  • Python：使用 uv pip install --python-platform aarch64-manylinux2014 --only-binary=:all: 下載與 arm64 相容的 wheel。

  • Node.js：在 arm64 機器上安裝原生模組或使用 npm install --arch=arm64 --platform=linux 。

  • 或者，在 AWS 以 Graviton 為基礎的 Amazon EC2 執行個體上建置您的相依性，以確保 arm64 相容性。

錯誤指標： "Your artifact contains binary files that are incompatible with Linux ARM64."

缺少進入點

發生這種情況時：在代理程式建立期間，指定的進入點檔案不存在於 ZIP 中。

發生這種情況的原因：您在entryPoint組態中指定的進入點檔案路徑與部署套件中的任何檔案不相符。如果檔案未包含在 ZIP 中、路徑拼寫錯誤，或 ZIP 結構與您預期的不同，就可能發生這種情況。

解決方案：

  • 確認您的 ZIP 中存在進入點檔案： unzip -l deployment_package.zip | grep app.js

  • 確保 中的路徑entryPoint符合 ZIP 中的檔案路徑 （包括任何子目錄，例如 src/app.js或 dist/index.js )

  • 對於 Python 代理程式，進入點必須以 .py 結尾；對於 Node.js 代理程式，其必須以 結尾 .js

錯誤指標： "The specified entrypoint could not be found or accessed in your artifact."

Node.js 不相容的 engine.node 宣告

發生這種情況時：當您package.json或常見的相依性宣告排除目標 Node.js 版本engines.node的範圍時，在 Node.js 代理程式建立期間。

發生這種情況的原因：AgentCore 執行期會檢查根目錄package.json和常見相依項中的 engines.node 欄位。如果版本範圍排除目標 Node.js 版本 （例如，<18或部署到 Node.js 22 >=14 <18時），代理程式建立會失敗。

解決方案：

  • 更新 中的 engines.node 欄位package.json，以包含目標 Node.js ">=18" 版本 （例如 )

  • 將任何不相容的相依性更新為支援目標 Node.js 版本的版本

  • 如果不需要，請移除 engines 欄位

錯誤指標： "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."