View a markdown version of this page

对直接代码部署进行故障排除 - 亚马逊基岩 AgentCore
AccessDenied: S3 权限不足AccessDenied: CMK 加密的 S3 对象访问权限CREATE_FAILED：代码包兼容性ARM64 二进制不兼容缺少入口点Node.js 不兼容的引擎。节点声明Node.js 缺少酒店套餐

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

Amazon Bedrock AgentCore 直接代码部署入门时的常见问题和解决方案。有关更多故障排除信息，请参阅 Amazon Bedrock AgentCore 运行时https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-troubleshooting.html疑难解答。

AccessDenied: S3 权限不足

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

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

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

{
"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 运行时支持的版本）。

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

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

错误指示器：

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

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

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

ARM64 二进制不兼容

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

为什么会发生这种情况： AgentCore 运行时仅支持 arm64 指令集架构。该服务会扫描部署包中的所有原生二进制.so文件（Python 文件.so及两者的.node Node.js 文件），并验证其 ELF 头文件是否与 ARM64 兼容。如果为 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.js 代理创建期间，当您package.json或公共依赖项声明的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 缺少酒店套餐

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

为什么会发生这种情况：当你使用时"entryPoint": ["opentelemetry-instrument", "app.js"]， AgentCore Runtime 期望 @aws/aws-distro-opentelemetry-node-autoinstrumentation npm 包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."