Hi team, @Rocky. We have a bunch of tables with the same number of buckets and same number of replicas. When trying to add them to a colocation group that has the same exact number of replicas and buckets, we get an error message saying the number of buckets is different. To solve this, for each table that we want to add, we first need to run an ALTER TABLE to set its buckets again (to the same value) and after that is done we can add to the group. Is this a known issue?

Based on your description, this behavior usually occurs when there is a mismatch between the table-level bucket count and the partition-level bucket count (or internal metadata), even if they appear the same in your SQL. Why this happens For a table to join a Colocation Group (CG), StarRocks requires every single partition within that table to have the exact same number of buckets as defined in the group. The error "number of buckets is different" is triggered if: 1. Dynamic/Automatic Bucketing: If the table was created with "Automatic Bucketing" (introduced in v2.5.7) or without an explicit

BUCKETS

count, StarRocks determines the bucket count per partition dynamically. Even if it happens to pick the same number as your group (e.g., 32), it is considered "dynamic" and may not satisfy the "static" requirement of the CG until forced. 2. Legacy Partitions: If you have an existing table where some partitions were created with a different bucket count (or even a different internal version of the bucket mapping) before you standardized the table's properties, the table as a whole cannot join the group. 3. Metadata Sync: In some versions, the Frontend (FE) check for colocation is very strict. It doesn't just check the

PROPERTIES

of the table; it validates the

BucketNum

of every physical partition. The Workaround is the "Official" Fix Running

ALTER TABLE ... DISTRIBUTED BY HASH(...) BUCKETS N

is the standard way to fix this. This is because: * It triggers a re-bucketing operation (a background task that redistributes data). * It ensures that all existing partitions are normalized to the exact same bucket count and distribution schema. * Once the background job completes, the table's metadata is updated to a "stable" state that the Colocation Group validation can accept. Recommendations * Check Partitions: You can verify if there is a discrepancy by running:

sql
    SHOW PARTITIONS FROM your_table_name;

Look at the

Buckets

column for every partition. If even one differs from the others or from the group, the addition will fail. * Explicit Creation: To avoid this for new tables, always specify the

colocate_with

property at

CREATE TABLE

time. This forces StarRocks to validate and fix the distribution immediately upon creation. * Check Group Status: After adding tables, monitor the group's health:

sql
    SHOW PROC '/colocation_group';

If you find that

SHOW PARTITIONS

confirms all buckets are identical but the error persists until you run the

ALTER

command, it is likely a metadata synchronization edge case in the FE. For more details on your specific StarRocks version, you can check the StarRocks Colocate Join documentation. References • using_starrocks/Colocate_join.md • best_practices/bucketing.md • faq/Sql_faq.md