1. 磁盘空间不足 #

常见场景：使用 Flink 做 Paimon 批处理任务（例如 Hive 存量文件转换等），在 Shuffle 使用本地磁盘的时候，单个容器磁盘不足以承担 Shuffle 文件数据量。

日志报错：Caused by: java.io.IOException: No space left on device 。

• 原因：单个 TM Pod Slot 个数太多，TM 磁盘不足；
• 解决方案：将单个 TM 的 Pod 的 Slot 调整到 1，并行度推荐 >= Paimon Bucket 个数（大于 Paimoin Bucket 个数主要是为了提高从 TOS 拉取的吞吐）；

2. JVM 堆内存不足 #

常见场景：使用 Flink 做 Paimon 的流式和批式处理过程中，由于数据量过大或者资源不足，会出现内存不够的情形。流入。

日志报错：Caused by: java.lang.OutOfMemoryError: Java heap space 。

• 原因：单个 TM Pod Slot 个数太多，TM 内存不足；
• 解决方案：将单个 TM 的 Pod 的 Slot 调整到 1，并行度推荐 >= Paimon Bucket 个数（大于 Paimoin Bucket 个数主要是为了提高从 TOS 拉取的吞吐）；

日志报错： GC overhead limit exceeded。

• 原因：单个 TM Pod Slot 个数太多，TM 内存不足；
• 解决方案：将单个 TM 的 Pod 的 Slot 调整到 1，并行度推荐 >= Paimon bucket 个数（大于 Paimoin Bucket 个数主要是为了提高从 TOS 拉取的吞吐）；

3. Paimon 单分桶内数据量过大，导致仍然 OOM #

场景说明：Flink 作业调整并发到 Paimon Bucket 个数且单个 TM Slot 为 1，通过 Flink UI 观察部分任务在运行，但仍然出现 OOM 等问题：

• 原因：举例发现个别表 9 亿数据， 总共 150GB+， Paimon bucket 个数只有 13 个，单个 bucket 数据量过大；
• 解决方案：停止写入 Flink 任务，调整分桶(ALTER TABLE xxx SET TBLPROPERTIES ('bucket' ＝ 'xxx')，推荐单桶的数据在 1.5G - 2G 之间最佳；更详细操作方式可以参考官网 Rescale Bucket 。

4. 外部数据表字段未对齐 #

日志报错： Caused by: org.apache.calcite.sql.validate.SqlValidatorException: Unknown target column 'order_id'

• 原因：Flink SQL 字段和外部目标表（如 LAS Catalog 中的数据表部分字段名和 Flink SQL 中不一致）字段未对齐；
• 解决方案：检查 Flink SQL 中的字段和外部目标表字段是否对齐后修改 Flink SQL。

5. 字段数量不同 #

日志报错： Cause: Different number of columns.

• 原因：外部 Source 和 Sink 字段个数不同；
• 解决方案：检查 Source 表和 Sink 表的字段是否完全对齐。

6. Paimon 分桶数据不均衡 #

Flink UI 显示不同的 task 处理的数据量差异几倍以上（数据严重不均衡），可能出现 OOM；

• 原因：Paimon 主键设置不合理导致无法使数据均衡分区；
• 解决方案：重新仔细检查 Paimon 主键设置是否合理，发现不合理后如果表中无数据则删除源表后使用新主键重建表；如已有数据则重建表，停止源表的数据写入，然后通过 Flink Batch 任务导入新表，最后增量写入作业切换到新表即可；

7. LAS 元数据对接常见问题 #

7.1 验证 SQL 时报错 #

如果在验证 SQL 的时候（点击验证按钮，或者上线时候自动检查 SQL）报错如下，形如 Caused by: org.apache.thrift.transport.TTransportException此类错误，说明当前连接 LAS 接口不同。请不要慌张，当前版本暂时无法在验证 SQL 阶段访问 LAS 元数据。

org.apache.flink.table.api.ValidationException: Unable to create catalog 'paimon_test1'.

Catalog options are:
'hive-conf-dir'='/opt/tiger/workdir'
'metastore'='hive'
'type'='paimon'
'uri'='thrift://lakeformation.las.cn-beijing.ivolces.com:48869'
'warehouse'='tos://flink-cwz-paimon/paimon_test1'
        at org.apache.flink.table.factories.FactoryUtil.createCatalog(FactoryUtil.java:511)
        ...
Caused by: java.lang.RuntimeException: Failed to determine if database default exists
        at org.apache.paimon.hive.HiveCatalog.databaseExistsImpl(HiveCatalog.java:223)
        ... 9 more
Caused by: org.apache.thrift.transport.TTransportException
        at org.apache.thrift.transport.TIOStreamTransport.read(TIOStreamTransport.java:132)
        ... 15 more

解决方案：任务上线过程中选择更多设置 - 跳过上线前的深度检查。

7.2 运行时访问 LAS 接口失败 #

在执行完 6. 上线任务并且启动任务后，如果发现任务失败，并且在日志中报如下类似错误，这个问题说明 LAS 的接口无法访问

Caused by: org.apache.hadoop.hive.metastore.api.MetaException: Could not connect to meta store using any of the URIs provided. Most recent failure: org.apache.thrift.transport.TTransportException

可能原因

1. 没有上传 hive-site.xml 文件，或者文件名不正确
   1. 解决方法：检查 hive-site.xml 是否成功上传到依赖文件中，并且文件名必须完全符合要求。
2. 访问 LAS 的 AK/SK 不正确，无法正确认证用户信息。
   1. 解决方法：检查 hive-site.xml 中 AccessKey 和 AccessKeySecret 是否正确。
3. 访问 LAS 的用户没有 IAM 的 LASFullAccess 权限，请联系管理者开通该权限
   1. 解决方法：联系主账号管理者，检查是否为用户开通 LASFullAccess 权限。

7.3 访问 LAS 报接口无权限 #

在执行完 6. 上线任务并且启动任务后，如果发现任务失败，并且在日志中报如下类似错误，这个问题说明 LAS 的接口没有成功授权

Caused by: org.apache.hadoop.hive.metastore.api.MetaException: Access denied: [DeniedPrivilege(resource:Resource{resourceScope='SCHEMA', catalogName='paimon_test1', schemaName='test_db'}, action:DESCRIBE)] for user: 31035840

解决方法：这个问题是因为在 LAS Catalog 中没有给指定账号赋予相关权限。请结合报错日志信息提示的 action，参考数据目录管理，为账号开通权限即可。

7.4 任务无法启动，报 LAS 数据库不存在 #

在执行完 6. 上线任务并且启动任务后，如果发现任务失败，并且运行事件中发现如下报错，org.apache.flink.table.catalog exceptions.DatabaseNotExistException

解决办法：这个原因是因为在 Flink 任务提交阶段，静态解析 SQL 的时候，当前不会去连接 LAS 获取已有的数据库。只要在 SQL 代码中加入以下语句：

CREATE TABLE IF NOT EXISTS test_db;

重新提交任务之后，就可以恢复正常。

7.5 hive-site.xml 格式不正确 #

在执行完 6. 上线任务并且启动任务后，如果发现任务失败，并且日志中发现如下报错，com.ctc.wstx.exc.WstxParsingException：

Caused by: java.lang.RuntimeException: com.ctc.wstx.exc.WstxParsingException: Illegal processing instruction target ("xml"); xml (case insensitive) is reserved by the specs.
 at [row,col {unknown-source}]: [2,5]

解决办法：这个原因是因为对接 LAS 元数据中依赖的 hive-site.xml 的格式可能不正确。需要检查 xml 文件是否符合语法规范。常见 xml 格式问题可以参考：

1. 文件开头的内容必须是 <?xml ...，在尖括号前方不能包含任何不可见字符、空格、空行等。
2. xml 文档内必须包含合法的标签，比如在内容中不能出现 < 、>、&等特殊字符，如果出现需要用 CDATA 语法标记为普通文本。

7.6 删除 LAS 的库表应该怎么操作 #

如果需要删除 LAS 元数据中的库表，需要同时手动删除 LAS 元数据中的库表信息，以及 TOS 目录上的数据库表的文件路径。如果仅仅删除 LAS 元数据或者仅仅删除 TOS 目录的数据都会造成数据不一致。报以下类似的错误，导致任务失败：

1. 仅删除 TOS 文件路径，但未删除 LAS 元数据

2. 仅删除 LAS 元数据，但未删除 TOS 文件数据

解决方案：判断属于哪一种情况，将已有的 LAS 元数据和 TOS 文件数据都删除后才能保证数据库表继续正常写入。

7.7 LAS 中数据表是非分区表，TOS 文件系统上却有分区 #

如果我们使用了分区表，但是发现 LAS 和 TOS 的表信息不同：

1. LAS 界面展示表为分区表

2. TOS 界面展示数据表已经产生分区

解决方案：Paimon 不会自动将表的分区信息同步到 LAS 元数据管理。如果需要在 LAS 元数据管理看到数据表的分区字段，需要在建表语句中增加如下 WITH 参数：

'metastore.partitioned-table' = 'true' -- 确定是否将分区信息同步到 LAS 元数据管理

需要注意的是：因为分区字段无法动态增加，增加参数后，需要将原有的数据表清掉（包括 LAS 元数据和 TOS 的数据文件），然后重新创建。

8. 如何使用 TOS 的 HNS 分层桶 #

问题描述：分层命名空间 HNS（Hierarchical NameSpace，简称分层桶），是对象存储 TOS 推出的一个全新的基于分层元数据管理的桶类型。在提供分层命名空间能力的同时兼顾了对象扁平化扩展性，提供对象语义与文件语义透明互通的能力，实现真正的一份数据多种访问协议，提升数据使用效率。
相比扁平桶，可以很好的支持目录级别的 mv 与 rename 操作，同时优化常见读操作 List 与目录 Head，提升数据处理效率与性能，能很好的满足大数据、数据湖和 AI 领域的使用场景。
而 Paimon + HNS 的配合能真正使用 HNS 的原子语义，在不同 Flink 任务之间同时提交的时候避免需要引入锁机制进行冲突解决。
使用方法：和大部分正常的 Paimon 使用方法一致，需要再在任务配置参数中额外增加自定义参数，即可正常使用

flink.plugins.filesystem.tos.proton.enabled: true

注意：当前功能暂时仅支持 Flink-1.16-volcano 版本。

9. Flink CDC 同步到 Paimon 相关问题 #

9.1 JDBC Driver 找不到错误 #

问题现象：如果任务启动失败，在日志中出现如下异常信息 Caused by: java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver。

解决方案：该问题是因为合规性原因，Flink CDC 没有内置 MySQL Driver，请参考 使用 JDBC 或者 MySQL-CDC 数据源 文档，下载 MySQL 官方 Driver （建议 8.0.27 版本），并且上传到 Flink CDC 任务的依赖文件中。

9.2 Flink CDC 任务全新启动后，无法新增数据 #

问题现象：在 Flink CDC 任务运行一段时间后，因为各种原因需要丢弃原来状态从全新的初始阶段开始同步。如果此时原来 Paimon 表没有删除，则会出现新数据无法写入的问题。
解决方案：这个是因为 Flink CDC Paimon 的数据下游存在缺陷，commit.user 固定不变，导致在 Paimon 写入的时候快照从 0 版本开始，因为落后当前 Paimon 表的版本，则会导致始终无法发布。有两种解决方案：

1. 在全新启动的时候，需要删除 TOS 上所有的 Paimon 文件，保证全量同步从头开始。
2. 在全新启动的时候，需要将 commit.user 变更成新的值，比如 commit.user: v2，可以保证当前新的 commit user 快照可以正常发布。

9.3 MySQL Datetime 和 Paimon Timestamp 类型时间有差异 #

问题现象：MySQL 的 datetime 是一个无时区信息的数据类型，很多用户会用这个类型存取本地时间。比如 UTC+8 时区的 2025-01-09 10:00:00。因为无法确认时区，所以 Flink & Paimon 会在转型过程中默认使用 UTC 时间戳。所以在写入 Paimon 之后，使用 UTC+8 的时间再去查看这个时间结果为 2025-01-09 18:00:00。导致与 MySQL 中时间出现差异。
解决方案：

1. 在 MySQL 中避免使用 datetime 类型字段，而采用有时区信息的 timestamp 类型字段。这样 Flink 会结合 server-time-zone 信息，进行时区转换
2. 如果 MySQL 无法避免使用 datetime 类型，可以在 MySQL datetime 类型字段中用 UTC 时间存储，比如 UTC+8 的 2025-01-09 10:00:00，在数据库中存储为 2025-01-09 02:00:00

9.4 CDC 任务启动失败，提示动态 Bucket 模式不支持 #

问题现象：Flink CDC 启动失败，报错包含如下关键信息Can't extract bucket from row in dynamic bucket mode如下图所示：

解决方案：当前 Flink CDC 版本暂不支持 Paimon 的动态分桶模式（bucket = -1）。所以需要在 Paimon Sink 中指定如下固定分桶的参数。

# 指定建表的时候指定的分桶数量，建议按照数据量进行合理设置
table.properties.bucket: 10

9.5 changelog-producer 应该如何选择 #

问题描述：Paimon 支持 changelog-producer 的选项，在 CDC 场景一般推荐使用哪个选项。
解决方案：Paimon 的 changelog-producer 功能支持下游 Flink 任务读取完整的变更日志，可以通过如下参数设置：

table.properties.changelog-producer: input

这个选项可以参考 Changelog 产出机制进行设置，在 CDC 场景下常见的设置有两种：

1. none：如果下游不需要，则设置成 none，或者不设置即可。
2. input：如果下游需要 changelog，因为 CDC 上游就是变更日志，所以直接选择 input 即可。