{"record":{"id":"68645ce2c0cd3ca5","repo":"apache/seatunnel","slug":"write-props-bucket-key-error","errorCode":"WRITE_PROPS_BUCKET_KEY_ERROR","errorMessage":"${cause.getMessage()}","messagePattern":"\\$\\{cause\\.getMessage\\(\\)\\}","errorType":"error_code","errorClass":"PaimonConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/catalog/PaimonCatalog.java","lineNumber":324,"sourceCode":"        return Identifier.create(tablePath.getDatabaseName(), tablePath.getTableName());\n    }\n\n    private void resolveException(Exception e) {\n        Throwable cause = e.getCause();\n        if (cause instanceof UnsupportedOperationException) {\n            String message = cause.getMessage();\n            if (message.contains(\"The type \")\n                    && message.contains(\" in primary key field \")\n                    && message.contains(\" is unsupported\")) {\n                throw new PaimonConnectorException(\n                        PaimonConnectorErrorCode.UNSUPPORTED_PRIMARY_DATATYPE, message);\n            }\n        } else if (cause instanceof RuntimeException) {\n            String message = cause.getMessage();\n            // https://github.com/apache/paimon/pull/3320/files#diff-d3e068ea8caf83d2371f0eaa1cbf3d02ff06e1c1cdceec5fab2e065cecd96230\n            if (message.contains(\n                    \"Cannot define 'bucket-key' with bucket -1, please specify a bucket number.\")) {\n                throw new PaimonConnectorException(\n                        PaimonConnectorErrorCode.WRITE_PROPS_BUCKET_KEY_ERROR, message);\n            }\n        }\n        throw new CatalogException(\"An unexpected error occurred\", e);\n    }\n\n    // --------------------------------------------------------------------------------------------\n    // SPI load paimon catalog\n    // --------------------------------------------------------------------------------------------\n\n    public static PaimonCatalog loadPaimonCatalog(ReadonlyConfig readonlyConfig) {\n        org.apache.seatunnel.api.table.factory.CatalogFactory catalogFactory =\n                discoverFactory(\n                        Thread.currentThread().getContextClassLoader(),\n                        org.apache.seatunnel.api.table.factory.CatalogFactory.class,\n                        PaimonSink.PLUGIN_NAME);\n        if (catalogFactory == null) {\n            throw new PaimonConnectorException(","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/catalog/PaimonCatalog.java#L306-L342","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Specify a positive bucket number (table property 'bucket' = N) together with bucket-key","Remove the bucket-key option to let dynamic-bucket mode choose keys automatically","Set the bucket option explicitly in the sink config","Review Paimon docs: bucket-key requires fixed bucket mode"],"exampleFix":"// before\nsink = { plugin_name=\"Paimon\", paimon.table.write-bucket-key=\"user_id\", ... }\n// after\nsink = { plugin_name=\"Paimon\", paimon.table.write-bucket-key=\"user_id\", paimon.table.props.bucket=\"4\", ... }","handlingStrategy":"validation","validationCode":"if (props.containsKey(\"bucket-key\")\n        && (!props.containsKey(\"bucket\") || Integer.parseInt(props.get(\"bucket\")) <= 0)) {\n    throw new IllegalArgumentException(\"bucket-key requires a positive 'bucket' value\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog.createTable(tablePath, catalogTable, false);\n} catch (PaimonConnectorException e) {\n    if (e.getErrorCode() == PaimonConnectorErrorCode.WRITE_PROPS_BUCKET_KEY_ERROR) {\n        LOG.error(\"bucket-key without fixed bucket: {}\", e.getMessage());\n    }\n}","preventionTips":["Always set an explicit positive 'bucket' when using bucket-key","Or drop bucket-key entirely and rely on dynamic bucket mode","Validate Paimon table properties before createTable","Document bucket settings in your sink config templates"],"tags":["paimon","bucket-key","configuration","create-table"],"backgroundTag":"conflicting-config-options","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}