Slackbot
05/05/2026, 2:38 PMRocky
05/05/2026, 2:38 PMALTER SYSTEM DECOMMISSION BACKEND is the correct approach as it triggers an asynchronous migration of all tablets to the remaining nodes.
* Concurrency Warning: StarRocks documentation generally recommends decommissioning nodes in small batches (no more than 2 at a time) to avoid overwhelming the remaining nodes with migration traffic and to maintain query performance. For 4 nodes, I recommend decommissioning 2, waiting for them to finish, and then decommissioning the next 2.
* Check Replicas: Ensure that your data's replication_num (default is 3) is less than the remaining 8 nodes. If you have any tables with a high replication factor (e.g., 8+), decommissioning will hang or fail.
* Check for Single-Replica Tables: If any tables have a replication_num of 1, the decommission process may fail if the target nodes cannot accommodate the data immediately.
2. Monitoring the Decommission
* Verification: Don't just wait for them to disappear. Use SHOW BACKENDS; and check the SystemDecommissioned column. Once the node is gone from the list, StarRocks has safely moved all data.
* Tablet Health: It is a good idea to run SHOW PROC '/statistic'; to ensure there are no "Unhealthy" tablets before proceeding to the Terraform phase.
3. Terraform & Instance Upgrades (The Risky Part)
Your plan to terraform apply to upgrade the instance types of the remaining 8 nodes is the most dangerous step.
* Avoid Simultaneous Restarts: Most cloud providers (AWS/GCP/Azure) require a stop/start or a replacement to change an instance type. If your Terraform configuration applies this change to all 8 nodes at once, your entire cluster will go offline.
* Recommended Approach:
1. Do not let Terraform update all 8 nodes at once.
2. Either use a Terraform module that supports rolling updates (e.g., an AWS Auto Scaling Group with an Instance Refresh) or—more commonly—update the instance type manually one by one.
3. For each node: Stop the BE $\rightarrow$ Change Instance Type $\rightarrow$ Start BE $\rightarrow$ Wait for it to show as Alive in SHOW BACKENDS $\rightarrow$ Move to the next.
* IP Pinning: Pinning private IPs is excellent. StarRocks uses the IP/Port as the unique identifier for BEs. If the IP changes, the FE will treat it as a new, empty node.
4. Refined Plan Strategy
1. Phase 1 (Scale In): Decommission 2 BEs, wait for completion. Decommission the next 2 BEs, wait for completion.
2. Phase 2 (Clean State): Run terraform apply to only remove the 4 decommissioned nodes from the state/infrastructure.
3. Phase 3 (Vertical Upgrade): Perform a rolling upgrade of the instance types for the 8 remaining nodes. If using Terraform for this, do it one node (or one small group) at a time by updating variables/targets specifically, or perform it manually to ensure the cluster stays up.
Summary Checklist
* [ ] SHOW BACKENDS shows all remaining nodes are healthy.
* [ ] SHOW PROC '/statistic' shows 0 unhealthy tablets.
* [ ] Verify replication_num on all tables is $\le 8$.
* [ ] Ensure Terraform won't reboot all 8 nodes simultaneously.
References
• administration/management/Scale_up_down.md
• deployment/plan_cluster.md
• knowledge/usage/best-practice.md
• best_practices/query_tuning/schema_tuning.md
• deployment/upgrade.mdRocky
05/05/2026, 3:14 PMUnhealthyTabletNum is stuck or decreasing very slowly while cluster_balance shows 0 pending tablets, it usually means the Tablet Checker has detected issues but the Tablet Scheduler is either not creating tasks or the tasks are failing/being throttled.
Here is a step-by-step troubleshooting guide to unstick the process:
1. Identify the Stuck Tablets
First, find out exactly which tablets are considered "unhealthy" and why.
1. Find the Database ID:
sql
SHOW PROC '/statistic';
Look for the DbId where UnhealthyTabletNum is greater than 0.
2. Get the Tablet IDs:
sql
-- Replace <db_id> with the ID from the previous step
SHOW PROC '/statistic/<db_id>';
This will return a list of UnhealthyTablets.
3. Inspect a specific tablet:
Pick a few tablet IDs from the list and run:
sql
SHOW TABLET <tablet_id>;
In the output, copy the command in the DetailCmd column and execute it. This will show you exactly where each replica is located and its status (e.g., VERSION_ERROR, MISSING, or if it's still sitting on the decommissioned node).
2. Check for Resource Throttling
If pending_tablets is 0, the scheduler might be skipping tasks due to resource limits or disk space.
* Disk High Watermark: Run SHOW BACKENDS; and check the AvailCap and DataUsedCap. If the remaining 8 nodes are over 85-90% full, StarRocks will stop scheduling new replicas to them.
_ _Fix:* Increase disk space or delete unnecessary data.
* Scheduling Slots: The FE limits how many concurrent tasks can run per BE path.
_ _Fix:* Temporarily increase the scheduling concurrency:
sql
ADMIN SET FRONTEND CONFIG ("tablet_sched_slot_num_per_path" = "16");
ADMIN SET FRONTEND CONFIG ("tablet_sched_max_scheduling_tablets" = "2000");
3. Check for "Blocking" Tablets
* Single-Replica Tables: If any table has replication_num = 1, the decommissioning process cannot "move" the data; it must create a new replica first. If there are constraints (like Colocate Groups or rack awareness), this can hang.
* Colocate Groups: If your tables are in a colocate_with group, the balancing is stricter. Check if the group is stable:
sql
SHOW PROC '/colocation_group';
If IsStable is false, the colocation balancer might be fighting with the decommission repair.
4. Force Repair
If you've identified a specific table that is stuck, you can force the FE to prioritize its repair:
sql
ADMIN REPAIR TABLE <table_name>;
This moves all unhealthy tablets of that table to the front of the scheduling queue with VERY_HIGH priority.
5. Check FE Logs (The "Why")
If the numbers still don't move, the Leader FE log is the source of truth. Search the fe.log for these keywords:
* TabletScheduler
* CloneTask
* schedule repair tablet
Look for error messages like no available backend to take replica or exceed max slot num.
Summary Checklist
1. Are the target BEs full? (Check SHOW BACKENDS)
2. Are there many small tablets? (Increases metadata overhead, speed up with tablet_sched_slot_num_per_path)
3. Is the Leader FE under heavy load? (Check FE JVM GC and CPU)
4. Are there tables with replication_num = 1? (These often require manual intervention or higher priority)
References
• administration/management/resource_management/Replica.md
• faq/operation_maintenance_faq.md