prestodb/presto · error · PrestoException

HIVE_INVALID_BUCKET_FILES

HIVE_INVALID_BUCKET_FILES

Error message

A row that is supposed to be in bucket %s is encountered. Only rows in bucket %s (modulo %s) are expected

What it means

When reading a bucketed table, HivePageSource filters pages to only rows of the bucket this split should keep. If a row's computed bucket is not congruent to bucketToKeep modulo partitionBucketCount, the split contains files from wrong buckets, so it throws HIVE_INVALID_BUCKET_FILES. This indicates corrupted or mis-bucketed files in the table.

Source

Thrown at presto-hive/src/main/java/com/facebook/presto/hive/HivePageSource.java:325

            this.bucketColumns = bucketAdaptation.getBucketColumnIndices();
            this.bucketToKeep = bucketAdaptation.getBucketToKeep();
            this.typeInfoList = bucketAdaptation.getBucketColumnHiveTypes().stream()
                    .map(HiveType::getTypeInfo)
                    .collect(toImmutableList());
            this.tableBucketCount = bucketAdaptation.getTableBucketCount();
            this.partitionBucketCount = bucketAdaptation.getPartitionBucketCount();
            this.useLegacyTimestampBucketing = bucketAdaptation.useLegacyTimestampBucketing();
        }

        @Nullable
        public Page filterPageToEligibleRowsOrDiscard(Page page)
        {
            IntArrayList ids = new IntArrayList(page.getPositionCount());
            Page bucketColumnsPage = page.extractChannels(bucketColumns);
            for (int position = 0; position < page.getPositionCount(); position++) {
                int bucket = getHiveBucket(tableBucketCount, typeInfoList, bucketColumnsPage, position, useLegacyTimestampBucketing);
                if ((bucket - bucketToKeep) % partitionBucketCount != 0) {
                    throw new PrestoException(HIVE_INVALID_BUCKET_FILES, format(
                            "A row that is supposed to be in bucket %s is encountered. Only rows in bucket %s (modulo %s) are expected",
                            bucket, bucketToKeep % partitionBucketCount, partitionBucketCount));
                }
                if (bucket == bucketToKeep) {
                    ids.add(position);
                }
            }
            int retainedRowCount = ids.size();
            if (retainedRowCount == 0) {
                return null; // Empty page after filtering
            }
            if (retainedRowCount == page.getPositionCount()) {
                return page; // Unchanged after filtering
            }
            Block[] adaptedBlocks = new Block[page.getChannelCount()];
            for (int i = 0; i < adaptedBlocks.length; i++) {
                Block block = page.getBlock(i);
                if (block instanceof LazyBlock && !((LazyBlock) block).isLoaded()) {

View on GitHub (pinned to 55bb57d202)

Solutions

1. Align the bucketing mode: set hive.legacy bucketing / bucketing_version session or table property to match how the data was written.
2. Check the table's bucketing_version in metastore and rewrite the affected partitions with the current engine.
3. Identify and fix misnamed/misplaced bucket files in the listed partition.
4. If the mismatch is only from a connector bug, upgrade Presto/Hive connector version.

Example fix

-- before (data written with old bucketing, read with new)
SELECT * FROM bucketed_table WHERE ...;
-- after
SET SESSION hive.legacy_bucketing = true;
SELECT * FROM bucketed_table WHERE ...;

-- verify bucketing metadata matches data layout
SHOW CREATE TABLE bucketed_table; -- check bucketing_version / bucket_count
-- confirm files per partition match bucket count
SELECT "$path" FROM bucketed_table WHERE dt = '2026-09-04';

catch (PrestoException e) {
    if ("HIVE_INVALID_BUCKET_FILES".equals(e.getErrorCode().getName())) {
        // retry with legacy bucketing session flag, or repair the partition
    }
}

When it happens

Trigger: filterPageToEligibleRowsOrDiscard computes getHiveBucket(...) for a row and (bucket - bucketToKeep) % partitionBucketCount != 0 — i.e. the reader received a page whose rows belong to another bucket than the split expects.

Common situations: Buckets written with a different bucketing version (legacy vs modern Hive bucketing, hive.legacy bucketing flag mismatch), files copied/misnamed after writes, manual file operations corrupting bucket-to-file mapping, table migrated between Hive versions.

Related errors

• HIVE_INVALID_BUCKET_FILES
• unknown java type
• HIVE_INVALID_BUCKET_FILES
• HIVE_INVALID_METADATA
• HIVE_INVALID_METADATA

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/43434163ae4f4b8e. Report an issue: GitHub.