View a markdown version of this page

对直接代码部署进行故障排除 - Amazon Bedrock AgentCore
AccessDenied: S3 权限不足AccessDenied: CMK 加密的 S3 对象访问权限CREATE_FAILED：代码包兼容性ARM64 二进制文件不兼容缺少入口点Node.js 不兼容的引擎.node 声明Node.js 缺少 OTEL Package

对直接代码部署进行故障排除

开始使用 Amazon Bedrock AgentCore 直接代码部署时的常见问题和解决方案。有关更多疑难解答信息，请参阅 Amazon Bedrock AgentCore 运行时疑难解答。

AccessDenied: S3 权限不足

发生这种情况时：在通过控制台、SDK 或 CLI 在 S3 中使用压缩项目创建代理或更新期间

为什么会发生这种情况：用于调 Create/UpdateAgentRuntime 用的角色没有 API 输入中传递的 S3: 对 S3 uri 的GetObject 权限。

解决方案：在角色中添加 s3：用于调用 Agentcore 运行时 create/update API 的GetObject 权限。

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

AccessDenied: CMK 加密的 S3 对象访问权限

发生这种情况时：在使用 CMK-encrypted S3 对象创建代理期间，执行角色缺乏 KMS 解密权限。

发生这种情况的原因：用于调用的角色对用于加密 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

解决方案：

要解决此问题，请执行以下操作：

  1. 确保已为 arm64 编译代码。

  2. 使用兼容的语言版本（选中 AgentCore Runtime 支持的版本）。

  3. 验证 ZIP 结构包含正确的入口点和依赖关系。

  4. 在兼容的运行时环境中重建软件包。

错误指示器：

  • 代理状态：CREATE_FAILED 或运行时错误

  • 在 cloudwatch 日志中导入错误或 “无法执行二进制文件” 消息

  • 当你遇到架构不匹配错误时。AgentRuntimeEndpoint

ARM64 二进制文件不兼容

发生这种情况时：在代理创建期间，当你的 ZIP 包含为非 ARM64 架构编译的本机二进制文件时。

为什么会发生这种情况： AgentCore 运行时仅支持 arm64 指令集架构。该服务会扫描部署包中的所有原生二进制文件（Python .node 文件.so和两者兼而有之 Node.js ），并验证它们的 ELF 标头是否兼容 ARM64。.so如果为 x86_64、macOS (Mach-O) 或其他架构编译了任何二进制文件，则验证将失败。

解决方案：

  • Python：uv pip install --python-platform aarch64-manylinux2014 --only-binary=:all:用于下载兼容 arm64 的轮子。

  • Node.js：在 arm64 计算机上安装本机模块或使用npm install --arch=arm64 --platform=linux。

  • 或者，在 AWS Graviton-based 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 不兼容的引擎.node 声明

发生这种情况时：在 Node.js 代理创建期间，当您的package.json或公共依赖项声明了一个不包括目标 Node.js 版本的engines.node范围时。

为什么会发生这种情况： AgentCore Runtime 会检查根目录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 Package

发生这种情况时：在 Node.js 代理创建过程中，当您在入口点opentelemetry-instrument中指定但 ADOT 包未包含在 ZIP 中时。

为什么会发生这种情况：当你使用时"entryPoint": ["opentelemetry-instrument", "app.js"]， AgentCore Runtime 期望你的部署包node_modules/中有 @aws/aws-distro-opentelemetry-node-autoinstrumentation npm 包。

解决方案：

在打包 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."