apache/seatunnel · error · PaimonConnectorException

WRITE_PROPS_BUCKET_KEY_ERROR

WRITE_PROPS_BUCKET_KEY_ERROR

Error message

${cause.getMessage()}

What it means

PaimonConnectorException with code WRITE_PROPS_BUCKET_KEY_ERROR, raised by resolveException during createTable when Paimon complains: "Cannot define 'bucket-key' with bucket -1, please specify a bucket number." It means a bucket-key was configured while the table uses dynamic (unspecified, -1) buckets, which Paimon forbids.

Source

Thrown at seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/catalog/PaimonCatalog.java:324

        return Identifier.create(tablePath.getDatabaseName(), tablePath.getTableName());
    }

    private void resolveException(Exception e) {
        Throwable cause = e.getCause();
        if (cause instanceof UnsupportedOperationException) {
            String message = cause.getMessage();
            if (message.contains("The type ")
                    && message.contains(" in primary key field ")
                    && message.contains(" is unsupported")) {
                throw new PaimonConnectorException(
                        PaimonConnectorErrorCode.UNSUPPORTED_PRIMARY_DATATYPE, message);
            }
        } else if (cause instanceof RuntimeException) {
            String message = cause.getMessage();
            // https://github.com/apache/paimon/pull/3320/files#diff-d3e068ea8caf83d2371f0eaa1cbf3d02ff06e1c1cdceec5fab2e065cecd96230
            if (message.contains(
                    "Cannot define 'bucket-key' with bucket -1, please specify a bucket number.")) {
                throw new PaimonConnectorException(
                        PaimonConnectorErrorCode.WRITE_PROPS_BUCKET_KEY_ERROR, message);
            }
        }
        throw new CatalogException("An unexpected error occurred", e);
    }

    // --------------------------------------------------------------------------------------------
    // SPI load paimon catalog
    // --------------------------------------------------------------------------------------------

    public static PaimonCatalog loadPaimonCatalog(ReadonlyConfig readonlyConfig) {
        org.apache.seatunnel.api.table.factory.CatalogFactory catalogFactory =
                discoverFactory(
                        Thread.currentThread().getContextClassLoader(),
                        org.apache.seatunnel.api.table.factory.CatalogFactory.class,
                        PaimonSink.PLUGIN_NAME);
        if (catalogFactory == null) {
            throw new PaimonConnectorException(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Specify a positive bucket number (table property 'bucket' = N) together with bucket-key
2. Remove the bucket-key option to let dynamic-bucket mode choose keys automatically
3. Set the bucket option explicitly in the sink config
4. Review Paimon docs: bucket-key requires fixed bucket mode

Example fix

// before
sink = { plugin_name="Paimon", paimon.table.write-bucket-key="user_id", ... }
// after
sink = { plugin_name="Paimon", paimon.table.write-bucket-key="user_id", paimon.table.props.bucket="4", ... }

if (props.containsKey("bucket-key")
        && (!props.containsKey("bucket") || Integer.parseInt(props.get("bucket")) <= 0)) {
    throw new IllegalArgumentException("bucket-key requires a positive 'bucket' value");
}

try {
    catalog.createTable(tablePath, catalogTable, false);
} catch (PaimonConnectorException e) {
    if (e.getErrorCode() == PaimonConnectorErrorCode.WRITE_PROPS_BUCKET_KEY_ERROR) {
        LOG.error("bucket-key without fixed bucket: {}", e.getMessage());
    }
}

When it happens

Trigger: createTable where table properties set 'bucket-key' but 'bucket' is unset or -1 (dynamic bucket mode); typically from user config keys like paimon.table.write-bucket-key combined with default bucket settings.

Common situations: User sets bucket-key for performance but leaves bucket count dynamic; copied configs where the 'bucket' key was removed; migrating a fixed-bucket table config to dynamic-bucket usage.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Table ${tablePath} already exists in catalog ${catalogName}
• An unexpected error occurred
• The value of${key} is required
• ${key} is required
• ${CommonError.convertToConnectorPropsBlankError(Paimon, prop

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/68645ce2c0cd3ca5. Report an issue: GitHub.