# Kafka 事件源映射错误的故障排除
以下主题针对在使用 Amazon MSK 或自托管式 Apache Kafka 和 Lambda 时可能遇到的错误和问题提供了故障排除建议。
有关故障排除的更多帮助，请访问 [AWS 知识中心](https://repost.aws/knowledge-center#AWS_Lambda)。
## 身份验证和授权错误
如果缺少使用来自 Kafka 集群的数据所需的任何权限，Lambda 会在 **LastProcessingResult** 下的事件源映射中显示以下错误消息。
**Topics**
+ [集群未能授权 Lambda](#kafka-authorize-errors)
+ [SASL 身份验证失败](#kafka-sasl-errors)
+ [服务器未能通过 Lambda 的身份验证](#kafka-mtls-errors-server)
+ [Lambda 未能对服务器进行身份验证](#kafka-mtls-errors-lambda)
+ [提供的证书或私有密钥无效](#kafka-key-errors)
### 集群未能授权 Lambda
对于 SASL/SCRAM 或 mTLS，此错误表明提供的用户不具有以下所有必需的 Kafka 访问控制列表（ACL）权限：
+ DescribeConfigs 集群
+ 描述组
+ 读取组
+ 描述主题
+ 读取主题
当您使用所需的 `kafka-cluster` 权限创建 Kafka ACL 时，请将主题和组指定为资源。主题名称必须与事件源映射中的主题一致。组名称必须与事件源映射的 UUID 一致。
向执行角色添加所需的权限后，更改可能需要几分钟才会生效。
下面是针对此问题启用[日志记录配置](esm-logging.md)后的 ESM 系统级日志示例：
```
{
"eventType": "ESM_PROCESSING_EVENT",
"timestamp": 1734567890123,
"resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE11111-1",
"eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/0",
"logLevel": "WARN",
"error": {
"errorMessage": "Not authorized to access topics: [my-topic]",
"errorCode": "org.apache.kafka.common.errors.TopicAuthorizationException"
}
}
```
### SASL 身份验证失败
对于 SASL/SCRAM 或 SASL/PLAIN，此错误表明提供的登录凭证无效。
对于 IAM 访问控制，此错误表明执行角色缺少集群的 `kafka-cluster:Connect` 权限。将此权限添加到该角色并将集群的 Amazon 资源名称（ARN）指定为资源。
您可能会看到此错误间歇性发生。在 TCP 连接数超过服务配额后，集群将拒绝连接。Lambda 会退回并重试，直到连接成功为止。在 Lambda 连接到集群并轮询记录后，最后的处理结果将更改为 `OK`。
下面是在使用 IAM 身份验证时针对此问题启用[日志记录配置](esm-logging.md)后的 ESM 系统级日志示例：
```
{
"eventType": "ESM_PROCESSING_EVENT",
"timestamp": 1734567890456,
"resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE22222-1",
"eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222/0",
"logLevel": "WARN",
"error": {
"errorMessage": "[a1b2c3d4-5678-90ab-cdef-EXAMPLE22222]: Access denied",
"errorCode": "org.apache.kafka.common.errors.SaslAuthenticationException"
}
}
```
### 服务器未能通过 Lambda 的身份验证
此错误表明 Kafka 代理未能对 Lambda 进行身份验证。出现此错误的可能原因如下：
+ 您没有为 mTLS 身份验证提供客户端证书。
+ 您提供了客户端证书，但未将 Kafka 代理配置为使用 mTLS 身份验证。
+ Kafka 代理不信任客户端证书。
### Lambda 未能对服务器进行身份验证
此错误表明 Lambda 未能对 Kafka 代理进行身份验证。出现此错误的可能原因如下：
+ 对于自托管式 Apache Kafka：Kafka 代理使用自签名证书或私有 CA，但未提供服务器根 CA 证书。
+ 对于自托管式 Apache Kafka：服务器根 CA 证书与签署代理证书的根 CA 不匹配。
+ 主机名验证失败，因为代理的证书未将该代理的 DNS 名称或 IP 地址用作主题替代名称。
### 提供的证书或私有密钥无效
此错误表明 Kafka 使用者无法使用提供的证书或私有密钥。确保证书和密钥使用 PEM 格式，并且私有密钥加密使用 PBES1 算法。
下面是针对此问题启用[日志记录配置](esm-logging.md)后的 ESM 系统级日志示例：
```
{
"eventType": "ESM_PROCESSING_EVENT",
"timestamp": 1734567891234,
"resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE44444",
"eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE44444-1",
"eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE44444/0",
"logLevel": "WARN",
"error": {
"errorMessage": "Invalid PEM keystore configs",
"errorCode": "org.apache.kafka.common.errors.InvalidConfigurationException"
}
}
```
## 网络和连接错误
网络配置问题可能会导致 Lambda 无法连接到您的 Kafka 集群。下面的主题介绍了常见的网络相关错误。
**Topics**
+ [由于安全组配置而导致连接超时](#kafka-security-group-errors)
+ [无法解析 Kafka 代理端点](#kafka-cluster-deleted-errors)
### 由于安全组配置而导致连接超时
如果与 Kafka 集群关联的安全组不允许来自自身的入站流量，则 Lambda 无法连接到该集群。确保安全组的入站规则允许来自安全组本身的流量通过 Kafka 代理端口。
下面是针对此问题启用[日志记录配置](esm-logging.md)后的 ESM 系统级日志示例：
```
{
"eventType": "ESM_PROCESSING_EVENT",
"timestamp": 1734567892345,
"resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE55555",
"eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE55555-1",
"eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE55555/0",
"logLevel": "WARN",
"error": {
"errorMessage": "Timeout expired while fetching topic metadata",
"errorCode": "org.apache.kafka.common.errors.TimeoutException"
}
}
```
您还可以查看 Kafka 使用者 INFO 日志，以验证连接和网络配置。`brokerEndpoints` 字段显示 Kafka 代理地址，`securityProtocol` 和 `saslMechanism`（如果适用）显示身份验证方法，`networkConfig` 字段显示事件源映射使用的 IP 地址、子网 CIDR 数据块和安全组。验证列出的安全组是否允许所需的入站流量：
```
{
"eventType": "POLLER_STATUS_EVENT",
"timestamp": 1734567892456,
"resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
"eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/a1b2c3d4-5678-90ab-cdef-11111EXAMPLE-1",
"eventProcessorId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE/0",
"logLevel": "INFO",
"kafkaEventSourceConnection": {
"brokerEndpoints": "boot-abcd1234.c2.kafka-serverless.us-east-1.amazonaws.com:9098",
"consumerId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE-0",
"topics": [
"my-topic"
],
"consumerGroupId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
"securityProtocol": "SASL_SSL",
"saslMechanism": "AWS_MSK_IAM",
"totalPartitionCount": 2,
"assignedPartitionCount": 2,
"partitionsAssignmentGeneration": 1,
"assignedPartitions": [
"my-topic-0",
"my-topic-1"
],
"networkConfig": {
"ipAddresses": [
"10.0.0.37"
],
"subnetCidrBlock": "10.0.0.32/28",
"securityGroups": [
"sg-0123456789abcdef0"
]
}
}
}
```
### 无法解析 Kafka 代理端点
此错误表明 Kafka 集群不存在或已遭删除。验证事件源映射中指定的集群是否存在并且处于活动状态。
下面是针对此问题启用[日志记录配置](esm-logging.md)后的 ESM 系统级日志示例：
```
{
"eventType": "ESM_PROCESSING_EVENT",
"timestamp": 1734567893456,
"resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE66666",
"eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE66666-1",
"eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE66666/0",
"logLevel": "WARN",
"error": {
"errorMessage": "No resolvable bootstrap urls given in bootstrap.servers",
"errorCode": "org.apache.kafka.common.config.ConfigException"
}
}
```
## 事件源映射错误
将 Apache Kafka 集群作为 Lambda 函数的[事件源](invocation-eventsourcemapping.md)添加时，如果您的函数遇到错误，Kafka 使用者将停止处理记录。主题分区的使用者是那些订阅、阅读和处理记录的使用者。您的其他 Kafka 使用者可以继续处理记录，只要他们没有遇到同样的错误即可。
要确定使用者停止的原因，请检查 `StateTransitionReason` 响应中的 `EventSourceMapping` 字段。下表列出了您可能收到的事件源错误：
**`ESM_CONFIG_NOT_VALID`**
事件源映射配置无效。
**`EVENT_SOURCE_AUTHN_ERROR`**
Lambda 无法对事件源进行身份验证。
**`EVENT_SOURCE_AUTHZ_ERROR`**
Lambda 没有访问事件源所需的权限。
**`FUNCTION_CONFIG_NOT_VALID`**
函数配置无效。
**注意**
如果您的 Lambda 事件记录超过允许的 6 MB 大小限制，那么它们可能处于未处理状态。