StarRocks 常见问题--E-MapReduce-火山引擎

文档中心

立即注册

导航

StarRocks 常见问题

最近更新时间：2025.11.13 17:28:37首次发布时间：2025.11.04 17:58:13

StarRocks 集群如何添加访问白名单

问题现象
连接StarRocks实例时，连接超时：

原因分析
连接 StarRocks 实例的主机或客户端IP地址未加入 StarRocks 实例的网络连接白名单。
解决方法

打开 StarRocks 实例，依次打开网络连接 > 白名单管理 > 入方向白名单 > 添加白名单组，完成添加后点击确定。

同一个 VPC 下面的连接实例，示例：
非同一个 VPC 下面的连接实例，请使用公网地址，示例：

注意

不建议设置0.0.0.0/0，若允许所有地址访问，将产生安全访问风险。

StarRocks 集群通过公网导入数据或查询时失败

问题现象

通过与 StarRocks 实例不在同一 VPC 下面的主机或客户端连接 StarRocks 实例时，连接超时或网络不通。

原因分析

需要通过公网地址连接 StarRocks 实例，并将目标主机的公网地址加入 StarRocks 实例的网络连接白名单。

解决办法
- 打开 StarRocks 实例详情，并依次打开网络连接 > 公网连接 > 开启公网 IP > 绑定公网 IP，选择可用的公网IP地址后，点击确定。若无可用的公网IP地址，请通过创建公网 IP 进行新建。
- 将目标主机的公网地址加入当前实例的白名单组，请参考StarRocks 集群如何添加访问白名单进行添加。

StarRocks 执行作业时报错内存不足

问题现象
在使用 StarRocks 进行数据快照备份时，遇到以下报错信息：

Memory limit exceeded: Memory of default_wg exceed limit. read and decompress page Backend: xxx.xxx.xxx.xxx, Used: **********, Limit: **********. Mem usage has exceed the limit of query...

原因分析
作业执行时使用的内存资源超出预期。
解决方法
- 参考 SQL 诊断使用说明查询优化对作业进行调优；
- 扩容或升配实例，详细操作请参考：
  - OLAP实例扩容：实例扩容。
  - OLAP实例升配：实例升配。

StarRocks 集群 Tablet 不均衡

说明

本章节仅适用于存算分离 StarRocks 实例。

问题现象
通过 show compute nodes; 查询 CN 节点上的 Tablet 数量，出现不均衡现象：
原因分析
扩容等操作完成后未执行 re-balance 操作，导致数据不均衡，且 StarRocks 自动均衡参数lake_enable_balance_tablets_between_workers默认值为false。
解决方法
- 通过以下命令开启自动均衡。

ADMIN SET FRONTEND CONFIG (lake_enable_balance_tablets_between_workers=true);

注意事项
- 开启自动均衡后会产生额外的资源消耗，建议业务低峰期进行操作，且在完成后关闭该设置；
- 存算分离场景下，长时间开启 Tablet 均衡会导致冷查询数量增加，增大查询延时。

StarRocks FE 连接池打满

问题现象

向 StarRocks 建立新连接时报下列错误。

com.starrocks.mysql.nio.AcceptListener$AfterConnectedException: Reach limit of connection

原因分析

集群新建连接数过多，达到FE或用户的连接数上限

解决办法

确认FE的连接数是否达到上限，打开 StarRocks 实例详情，并依次打开监控告警 > FE 连接数情况查看监控情况。

如果连接数达到 FE 配置 qe_max_connection 所设定的上限，则修改该参数至合理阈值，并重启 FE 使其生效。
若监控表示未达到 FE 配置 qe_max_connection 所设定的上限，则是由于达到了 User 级别的连接数上限。

-- 查看user的连接数上限
show property for '用户名';

-- 修改user级的连接数限制
set property for '用户名' 'max_user_connections' = 'xxx';

StarRocks BE jdbc 连接池已达到配置的最大连接数上限

问题现象
向 StarRocks 实例写入数据时报下列错误，且定位到 BE 连接数已达到上限：

Caused by: java.sql.SQLTransientConnectionException: seetong-siot-tsl - Connection is not available, request timed out after 30006ms.

原因分析

通过 JDBC 的方式连接 StarRocks 实例，并通过 Insert Into 的方式向实例中写入数据，导致连接数量快速上涨。

解决方法
- 临时止损：jdbc_connection_pool_size 默认值为8，调整连接上限至1024后重启 BE 节点生效。
- 通过 Stream Load 等方式进行数据导入，避免使用 Insert Into 方式写入数据。
参考资料
- 通过 Stream Load 方式导入数据：Stream Load。
- 通过 Broker Load 方式导入数据：Broker Load。

StarRocks Compaction 加载索引太慢

问题现象
Compaction 任务卡在 Publish Version 阶段，一直未结束，通过调查发现是由于加载索引太慢引起。
原因分析
- 主键索引的本地缓存时间设置较小，当导入间隔大于该缓存时限时，引起主键索引的重复加载。
- 主键索引的本地缓存内存设置较小，当导入数据量较大时，引起重复加载。

解决方法

扩大缓存过期时间。

UPDATE information_schema.be_configs SET VALUE = 3600 WHERE name = "lake_local_pk_index_unused_threshold_seconds";

根据 BE/CN 节点的内存使用情况，调整缓存空间。

-- 设置自定义参数lake_metadata_cache_limit为2GB
UPDATE information_schema.be_configs SET VALUE = 2147483648 WHERE name = "lake_metadata_cache_limit";

StarRocks CN 节点磁盘存储占用过大

问题现象

客户存算分离场景中 CN 节点磁盘使用率过高。

原因分析

数据缓存占用的本地磁盘空间较多，导致磁盘空间不足。

解决方法

调整本地数据缓存占用磁盘空间的比例，或考虑对 CN 节点的磁盘进行扩容。

-- 存算分离模式下启用 file data cache，如果当前剩余磁盘空间（百分比）低于此配置项中指定的值，将会触发缓存淘汰
starlet_cache_evict_low_water=0.2
-- 在存算分离模式下启用 file data cache，如果当前剩余磁盘空间（百分比）高于此配置项中指定的值，将会停止缓存淘汰
starlet_cache_evict_high_water=0.3 
-- 存算分离模式下，data cache 最多可使用的磁盘容量百分比
starlet_star_cache_disk_size_percent=70

StarRocks FE 节点内存使用率超过90%

问题现象

StarRocks 集群 FE 节点内存使用率逐渐升高，超过90%，且 JVM Heap 内存也一直处于高位：

原因分析

FE 节点内存使用设置不合理，导致内存使用一直处于高位。

解决方法
通过 Xmx 调整内存使用限制，降低内存使用占比，请根据节点的内存总量进行调整，示例：
调整前：-Xms13107m -Xmx49152m
调整后：-Xms13107m -Xmx45875m

StarRocks 报错`get database read lock timeout`

问题现象

实时任务向 StarRocks 实例中写入数据失败，报错信息：

Caused by: com.bytedance.bitsail.common.BitSailException: LOAD_FAILED - StarRocks load status is not success, response content: {"existingJobStatus":null,"label":"_1761718530459_ed7721edca174dffa1f456359c4a4cf8","txnId":577316498,"status":"Fail","message":"get database read lock timeout... ...

原因分析

异步物化视图操作中涉及了跨库操作，引起死锁。

解决方法
- 低版本 StarRocks 不建议使用物化视图，详情参见开源组件使用限制。
- 避免使用异步物化视图，尤其是涉及跨库操作时。

StarRocks 大查询导致资源耗尽

问题现象

单个查询/作业将 CPU 使用率达到100%，并持续10秒以上，大量挤占集群资源，导致业务正常的查询失败或者延时增加。

排查思路
- 参考大查询定位定位正在运行的大查询。
解决办法

根据大查询定位的结果，将大查询手动终止；并结合业务使用与查询审计日志表进行查询治理。

可基于大查询防御来部署防御策略，以降低未知大查询带来的业务影响。
可基于 SQL 诊断使用说明对查询进行调优。

StarRocks Compaction Score 过高

问题现象

StarRocks 集群读写性能下降或报错，通过监控发现 BE/CN 节点上的 Compaction Score 过高。

原因分析

Compaction score 过高，说明当前集群小文件较多，根本原因是由于写入频率与小文件的合并效率不匹配。

解决方法
- 建议降低客户端写入频率，增大客户端数据攒批，避免产生大量小文件。
- 在资源允许的情况下，参考存算分离集群 Compaction 提高 Compaction 的并发度。

StarRocks BE Tablet Version 超限

说明

该说明仅适用于存算一体 StarRocks 实例。

问题现象

Tablet version 数量超出限制，写入操作时出现错误：

ERROR 5025 (HY000): Failed to load data into tablet XXXX, because of too many versions, current/limit: 1005/1000. You can reduce the loading job concurrency, or increase loading data batch size. If you are loading data with Routine Load, you can increase FE configs routine_load_task_consume_second and max_routine_load_batch_size... ...

原因分析

上述报错是因为导入频率太快，数据没能及时合并 (Compaction) ，从而导致版本数超过支持的最大未合并版本数。默认支持的最大未合并版本数为 1000。

解决方法
- 动态调整的方法

-- StarRocks引擎（存算一体）
UPDATE information_schema.be_configs SET VALUE = 1500 WHERE name = "tablet_max_versions";

StarRocks 事务超限

问题现象

写入事务数量超出限制，写入操作时出现错误：

current running txns on db xxxx is xxxx, larger than limit xxxx

问题排查
- 查看每个 database 的事务积压情况。

-- StarRocks
show proc '/transactions';
-- 查看每个db的情况
show proc '/transactions/${db_id}';
-- 查看已完成的导入事务 找到失败事务 查看原因
show proc '/transactions/${db_id}/finished';

解决方法

动态将事务上限提高，让事务先进来，缓解上游写入任务的时延。

-- 调整FE配置（默认1000）
admin set frontend config ("max_running_txn_num_per_db" = "2000")

评估集群资源水位情况，考虑升配或扩容。

StarRocks 写入报错 `too many filter rows`

问题现象

数据写入 StarRocks 时失败，报错提示 too many filtered rows。举例：

{
  "Status": "Fail",
  "BeginTxnTimeMs": 101,
  "Message": "too many filtered rows",
  "NumberUnselectedRows": 0,
  "CommitAndPublishTimeMs": 0,
  "Label": "xxxxxxxxx",
  "LoadBytes": 245396,
  "StreamLoadPlanTimeMs": 102,
  "NumberTotalRows": 984,
  "WriteDataTimeMs": 265,
  "TxnId": 13787,
  "LoadTimeMs": 469,
  "ErrorURL": "http://xx.xx.xx.xx:8040/api/_load_error_log?file=error_log_5a4aad49f7900ad7_9dec92739f8027b7",
  "ReadDataTimeMs":0,
  "NumberLoadedRows":0,
  "NumberFilteredRows":984
}

问题排查

StarRocks 为保证数据质量，默认会对写入数据进行合法性校验，当数据不符合 StarRocks 表的字段类型时，会被过滤掉。当过滤行占总行数的比例超过阈值时，系统会终止写入，避免大量无效数据占用资源或破坏数据一致性。
用户可通过报错信息中的url查看具体的报错原因，常见原因有：

数据本身存在问题（脏数据）。
字段分区配置错误，如：列字段无法对齐、类型不一致等。

解决办法
- 规范数据源头校验：在上游业务系统中添加数据校验逻辑（如类型检查、格式校验、约束校验），从源头减少脏数据；
- 合理设置容错率：生产环境中 max_filter_ratio 建议设置为 0.05~0.1（5%-10%），既允许少量偶发脏数据，又避免大量无效数据写入。
- 更多操作可参考数据导入故障排查。

E-MapReduce