apache/seatunnel · error · PaimonConnectorException

CONFIG_VALIDATION_FAILED

CONFIG_VALIDATION_FAILED

Error message

PluginName: %s, PluginType: %s, Message: %s (Cannot find paimon catalog factory)

What it means

PaimonConnectorException with code CONFIG_VALIDATION_FAILED thrown by loadPaimonCatalog when no SeaTunnel CatalogFactory for the Paimon plugin can be discovered on the current thread's context classloader — i.e. the Paimon connector plugin/factory is missing from the plugin discovery path.

Source

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

                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,
                            PluginType.SINK,
                            "Cannot find paimon catalog factory"));
        }
        return (PaimonCatalog)
                catalogFactory.createCatalog(catalogFactory.factoryIdentifier(), readonlyConfig);
    }

    // --------------------------------------------------------------------------------------------
    // alterTable
    // --------------------------------------------------------------------------------------------

    public void alterTable(
            Identifier identifier, SchemaChange schemaChange, boolean ignoreIfNotExists) {
        try {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Install the Paimon connector jar into $SEATUNNEL_HOME/connectors (sh bin/install-plugin.sh)
2. Verify META-INF/services/org.apache.seatunnel.api.table.factory.Factory contains the Paimon catalog factory in the jar
3. Ensure the plugin is on the process classpath (check classloader.resolve-order settings)
4. If embedding SeaTunnel, set the context classloader before calling loadPaimonCatalog

Example fix

// before: connector missing
sh bin/seatunnel.sh --config job.conf -e local
// after: install plugin first
sh bin/install-plugin.sh
sh bin/seatunnel.sh --config job.conf -e local

// before submitting the job
if (new java.io.File("/opt/seatunnel/connectors/connector-paimon").getParentFile()
        .list((d, n) -> n.startsWith("connector-paimon")) == null) {
    throw new IllegalStateException("paimon connector jar not installed");
}

try {
    PaimonCatalog catalog = new PaimonCatalog(...);
    catalog.open(...);
} catch (PaimonConnectorException e) {
    if (e.getErrorCode() == SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED) {
        throw new IllegalStateException("Install connector-paimon: sh bin/install-plugin.sh", e);
    }
}

When it happens

Trigger: Classloader lacks the paimon connector factory (connector jar not installed in SEATUNNEL_HOME/connectors), SPI service file not on classpath, or plugin name mismatch during FactoryUtil discovery.

Common situations: Running seatunnel.sh without connector-paimon jar installed (install-plugin.sh not run); fat-jar builds excluding META-INF/services entries; custom classloader setups where Thread.currentThread().getContextClassLoader() differs from the app classloader.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED
• Could not find any factories that implement '${factoryClass}
• No data type converter found for identifier: ${identifier}
• No data converter found for identifier: ${identifier}
• No type converter found for identifier: ${identifier}

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