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

# 对直接代码部署进行故障排除
<a name="runtime-code-deploy-common-issues"></a>

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

## AccessDenied: S3 权限不足
<a name="permission-issues-s3"></a>

 **发生这种情况时：**在通过控制台、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 对象访问权限
<a name="permission-issues-cmk"></a>

 **发生这种情况时：**在使用 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：代码包兼容性
<a name="code-package-compatibility"></a>

 **发生这种情况时：**在使用不兼容的代码包（错误的架构、语言版本或包格式）创建代理或更新期间。

 **为什么会出现这种情况：**上传的 ZIP 文件包含针对错误架构（ARM64 与 x86\_64）、不兼容的语言版本或不符合运行时要求的错误包结构编译的二进制文件。 AgentCore 

 **解决方案：**

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

1. 确保代码是为 arm64 编译的。

1. 使用兼容的语言版本（请查看 AgentCore 运行时支持的版本）。

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

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

 **错误指示器：**
+ 代理状态：CREATE\_FAILED 或运行时错误
+ 在 cloudwatch 日志中导入错误或 “无法执行二进制文件” 消息
+ 当你遇到架构不匹配时会出错。AgentRuntimeEndpoint

## ARM64 二进制不兼容
<a name="arm64-binary-incompatibility"></a>

 **发生这种情况时：**在代理创建期间，当您的 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`。
+ 或者，在 Amazon Graviton-based Amazon EC2 实例上构建依赖关系，以确保 arm64 兼容性。

 **错误指示器：**`"Your artifact contains binary files that are incompatible with Linux ARM64."`

## 缺少入口点
<a name="missing-entry-point"></a>

 **发生这种情况时：**在代理创建期间，您的 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 不兼容的引擎。节点声明
<a name="node-incompatible-engines"></a>

 **发生这种情况时：**在 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 缺少酒店套餐
<a name="node-missing-otel-package"></a>

 **发生这种情况时：**在 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."`