prestodb/presto · error · PrestoException

HIVE_TABLE_BUCKETING_IS_IGNORED

HIVE_TABLE_BUCKETING_IS_IGNORED

Error message

Table bucketing is ignored. The virtual "$bucket" column cannot be referenced.

What it means

Thrown when a query references the virtual "$bucket" column but the split has no bucket number available, meaning table bucketing is effectively ignored (e.g. no bucketing info or legacy/local mode where buckets aren't tracked). Presto cannot return the $bucket value without bucket context.

Source

Thrown at presto-hive/src/main/java/com/facebook/presto/hive/HiveUtil.java:1031

    }

    @Nullable
    public static String columnExtraInfo(boolean partitionKey)
    {
        return partitionKey ? "partition key" : null;
    }

    public static Optional<String> getPrefilledColumnValue(HiveColumnHandle columnHandle, HivePartitionKey partitionKey, HiveFileSplit fileSplit, OptionalInt bucketNumber)
    {
        if (partitionKey != null) {
            return partitionKey.getValue();
        }
        if (isPathColumnHandle(columnHandle)) {
            return Optional.of(fileSplit.getPath());
        }
        if (isBucketColumnHandle(columnHandle)) {
            if (!bucketNumber.isPresent()) {
                throw new PrestoException(HIVE_TABLE_BUCKETING_IS_IGNORED, "Table bucketing is ignored. The virtual \"$bucket\" column cannot be referenced.");
            }
            return Optional.of(String.valueOf(bucketNumber.getAsInt()));
        }
        if (isFileSizeColumnHandle(columnHandle)) {
            return Optional.of(String.valueOf(fileSplit.getFileSize()));
        }
        if (isFileModifiedTimeColumnHandle(columnHandle)) {
            return Optional.of(String.valueOf(fileSplit.getFileModifiedTime()));
        }
        throw new PrestoException(NOT_SUPPORTED, "unsupported hidden column: " + columnHandle);
    }

    public static void closeWithSuppression(RecordCursor recordCursor, Throwable throwable)
    {
        requireNonNull(recordCursor, "recordCursor is null");
        requireNonNull(throwable, "throwable is null");
        try {
            recordCursor.close();

View on GitHub (pinned to 55bb57d202)

Solutions

1. Remove "$bucket" from the SELECT list / predicates
2. Ensure the table is properly bucketed and read through a path that tracks bucket numbers (configured bucketing on the metastore table)
3. Recreate the table with CLUSTERED BY ... INTO n BUCKETS if it should be bucketed

Example fix

-- before
SELECT "$bucket", * FROM db.t;
-- after
SELECT * FROM db.t;

-- verify the table is bucketed and query does not use "$bucket"
SHOW CREATE TABLE db.t; -- CLUSTERED BY (...) INTO n BUCKETS must be present
tableProps.getProperty("bucketing_version");

boolean canUseBucketColumn(String ddl) {
    return ddl != null && ddl.contains("CLUSTERED BY") && ddl.contains("BUCKETS");
}

try { rs = stmt.executeQuery(sql); }
catch (com.facebook.presto.spi.PrestoException e) {
    if (e.getMessage().contains("$bucket")) { /* drop $bucket from query or re-bucket table */ }
    else throw e;
}

When it happens

Trigger: SELECT "$bucket" FROM a Hive table in a context where bucketNumber is empty — e.g. the table/split was read without bucket tracking (bucketing ignored, unbucketed path, or a split source that doesn't populate bucket numbers).

Common situations: Queries against symlink/manifest or non-bucketed tables attempting "$bucket"; reads where bucketing validation was disabled; connector-internal reads that don't carry bucket ids.

Related errors

• unknown java type
• HIVE_INVALID_BUCKET_FILES
• HIVE_INVALID_METADATA
• HIVE_INVALID_METADATA
• Unsupported bucket function type

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