对 Snowflake Connector for Kafka 进行故障排除¶

通道报告 rows_error_count 增加¶

如果 Snowpipe Streaming 通道报告 rows_error_count 不断增加，连接器的行为取决于 errors.tolerance 设置：

• 使用 errors.tolerance=none``（默认）时，连接器任务失败并报错 ``ERROR_5030。

• 使用 errors.tolerance=all 时，连接器继续运行但记录错误计数。

调查方法：

1. 检查与目标表关联的错误表以识别失败的记录。有关详细信息，请参阅 Error handling in Snowpipe Streaming high-performance architecture。

2. 使用 使用元数据偏移检测并恢复错误 中描述的间隙查找技术，结合 RECORD_METADATA 列中的 Kafka 偏移信息。

3. 查看连接器日志以获取错误详细信息（启用 errors.log.enable=true 可获得详细日志记录）。

连接器任务失败，报错 ERROR_5030¶

ERROR_5030 表示连接器检测到数据摄入错误。常见原因包括：

• Kafka 记录与目标表模式之间的数据类型不匹配。

• 在配置了 snowflake.validation=client_side 的情况下存在用户创建的管道。客户端验证仅适用于默认管道。

• Kafka 记录中的模式发生了无法自动演化的更改。

解决方法：

1. 查看错误消息和连接器日志以确定具体原因。

2. 如果在使用用户定义管道时启用了客户端验证，请切换到 snowflake.validation=server_side 或删除用户定义的管道。

3. 修复源 Kafka 主题中的数据或调整目标表模式。

模式演化问题¶

对于服务器端验证，模式演化并不总能推断出正确的数据类型。例如，它无法推断二进制列，并且可能将像 "2026-04-13" 这样的字符串解释为 DATE 而不是 TEXT。

如果模式演化产生了意外的列类型：

• 使用客户端验证 (snowflake.validation=client_side) 以获得更好的类型推断。

• 在启动连接器之前预先创建具有正确模式的表。

身份验证失败¶

v4 连接器仅支持密钥对身份验证。常见的身份验证问题：

• 私钥无效：验证 snowflake.private.key 值是否为有效的 Base64 编码的 PKCS#8 私钥。

• 密钥密码：如果您的密钥已加密，请将 snowflake.private.key.passphrase 设置为正确的密码。

• 角色权限：验证 snowflake.role.name 中指定的角色是否具有所需的权限。有关详细信息，请参阅 Snowflake Connector for Kafka：选择使用 时默认使用的角色和仓库。配置 Snowflake。

授权错误¶

如果连接器遇到来自 Snowflake 的授权错误，其行为取决于 enable.task.fail.on.authorization.errors 设置：

• 使用 ``enable.task.fail.on.authorization.errors=false``（默认）时，连接器会进行重试。

• 使用 enable.task.fail.on.authorization.errors=true 时，连接器任务会立即失败。

转换器不支持自动格式演化¶

当使用 snowflake.enable.schematization=true``（默认）时，``StringConverter 和 ByteArrayConverter 不作为值转换器受到支持。请改用架构化转换器：

• org.apache.kafka.connect.json.JsonConverter

• io.confluent.connect.avro.AvroConverter

• io.confluent.connect.protobuf.ProtobufConverter

已移除的 v3 配置属性¶

如果您看到关于无法识别的配置属性的错误，请检查您是否使用了 v4 中已移除的属性。有关已移除配置的完整列表，请参阅 从 Kafka Connector v3 迁移到 v4。

启动时兼容性验证器失败¶

如果连接器在启动时失败，并出现关于缺失或不兼容配置值的错误，则兼容性验证器 (snowflake.streaming.validate.compatibility.with.classic) 正在根据 v3 迁移要求检查您的配置。

• 对于新安装：设置 snowflake.streaming.validate.compatibility.with.classic=false 以跳过检查。

• 对于从 v3 迁移：显式设置所有必需的兼容性属性。请参阅 snowflake.streaming.validate.compatibility.with.classic 获取完整列表。

引入延迟不断增加¶

如果 latest-consumer-offset 减去 persisted-in-snowflake-offset 的差值在增加（可通过 JMX 指标 查看），则表示连接器正在落后。

解决方法：

• 增加任务：将 tasks.max 设置为接近 Kafka 分区的总数。在 Kafka Connect 集群中，每个 CPU 核心通常对应 2 个任务可获得最佳性能。

• 检查背压：如果 backpressure-rewind-count 指标正在增加，则表示 Snowpipe Streaming SDK 已达到容量上限。考虑横向扩展您的 Kafka Connect 集群。

• 审查 JVM 内存：将 JVM 堆内存限制在可用内存的约 50%。基于 Rust 的 Snowpipe Streaming SDK 使用堆外内存进行缓冲，这部分内存不受 JVM 管理。

表和管道缓存¶

连接器会缓存表和管道存在性检查的结果，以减少数据库查询。如果您遇到连接器无法检测到新创建的表或管道的问题，请调整缓存过期时间：

snowflake.cache.table.exists.expire.ms=60000
snowflake.cache.pipe.exists.expire.ms=60000

持续通道恢复¶

通道偶尔恢复是正常的。但是，如果 channel-recovery-count 指标持续增加，可能表明：

• 目标表的模式发生了与连接器缓存的模式相冲突的更改。

• 影响连接器角色的权限发生了更改。

• Kafka Connect 集群与 Snowflake 之间的网络不稳定。

请查看连接器日志以获取具体的恢复原因。

SDK 客户端泄漏¶

如果 sdk-client-count JMX 指标持续增长，则连接器可能存在 Snowpipe Streaming SDK 客户端泄漏。每个不同的目标表应该只有一个 SDK 客户端。如果客户端数量超过了不同表的数量，请联系 Snowflake 支持部门。

偏移迁移期间未找到 SSv1 通道¶

如果连接器在使用 snowflake.streaming.classic.offset.migration=strict 时失败并出现通道未找到的错误：

• 验证您使用的连接器名称与 v3 部署中的名称相同。

• 检查 snowflake.streaming.classic.offset.migration.include.connector.name 是否与您的 v3 设置中的 snowflake.streaming.channel.name.include.connector.name 匹配。

• 如果通道已被清理，或者您正在添加 v3 中不存在的新主题，请切换到 best_effort 模式。

迁移后出现重复数据¶

如果您在从 v3 迁移后看到重复记录：

• 验证 RECORD_METADATA 包含主题、分区和偏移字段。

• 使用 从 v4 降级到 v3 中的去重查询来移除重复数据。