apache/seatunnel · error · CatalogException

An unexpected error occurred

Error message

An unexpected error occurred

What it means

Generic CatalogException('An unexpected error occurred', e) thrown by PaimonCatalog.resolveException when createTable fails with a cause matching none of the recognized patterns (unsupported primary-key type, bucket-key error). The original Paimon exception is attached as the cause.

Source

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

        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(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    String.format(
                            "PluginName: %s, PluginType: %s, Message: %s",
                            PaimonSink.PLUGIN_NAME,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the cause chain (getCause) for the real Paimon exception message
2. Verify paimon warehouse / metastore configuration and connectivity
3. Validate the table schema: field names unique, types supported by Paimon
4. Align connector and Paimon runtime versions; if a new Paimon message is misclassified, extend resolveException mapping

Example fix

// inspect root cause
try {
    catalog.createTable(tablePath, catalogTable, false);
} catch (CatalogException e) {
    LOG.error("createTable failed, root cause:", e.getCause());
    throw e;
}

// validate schema and catalog config up front
catalog.listDatabases(); // fail fast if warehouse/metastore unreachable

try {
    catalog.createTable(tablePath, catalogTable, false);
} catch (CatalogException e) {
    LOG.error("createTable failed; root cause:", e.getCause());
    throw e;
}

When it happens

Trigger: createTable failing for any unrecognized reason: invalid schema, warehouse access errors, metastore connectivity, corrupt table metadata, or newer Paimon exception messages not yet mapped by resolveException.

Common situations: Misconfigured warehouse path or HDFS permissions; Paimon version mismatch producing new error messages; invalid column types or duplicate field names in schema; filesystem full or metastore down.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Table ${tablePath} already exists in catalog ${catalogName}
• WRITE_PROPS_BUCKET_KEY_ERROR
• Failed to create BigQuery table:
• TableAlreadyExistException: catalogName, tablePath
• Failed to create table: ${tablePath}

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