apache/seatunnel · error · ConnectException

Unable to instantiate the database history class " + config.

Error message

Unable to instantiate the database history class " + config.getString(HistorizedRelationalDatabaseConnectorConfig.DATABASE_HISTORY)

What it means

In the vendored Debezium code inside connector-cdc-base, getDatabaseHistory instantiates the class named by the 'database.history' config property via reflection. If config.getInstance returns null (class missing on the classpath, not a DatabaseHistory, or the property is unset with no default), a ConnectException is thrown saying the database history class could not be instantiated.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-base/src/main/java/io/debezium/relational/HistorizedRelationalDatabaseConnectorConfig.java:149

                tableIdMapper,
                DEFAULT_SNAPSHOT_FETCH_SIZE,
                columnFilterMode);
        this.useCatalogBeforeSchema = useCatalogBeforeSchema;
        this.logicalName = logicalName;
        this.connectorClass = connectorClass;
        this.multiPartitionMode = multiPartitionMode;
    }

    /** Returns a configured (but not yet started) instance of the database history. */
    public DatabaseHistory getDatabaseHistory() {
        Configuration config = getConfig();
        DatabaseHistory databaseHistory =
                config.getInstance(
                        HistorizedRelationalDatabaseConnectorConfig.DATABASE_HISTORY,
                        DatabaseHistory.class,
                        () -> HistorizedRelationalDatabaseConnectorConfig.class.getClassLoader());
        if (databaseHistory == null) {
            throw new ConnectException(
                    "Unable to instantiate the database history class "
                            + config.getString(
                                    HistorizedRelationalDatabaseConnectorConfig.DATABASE_HISTORY));
        }

        // Do not remove the prefix from the subset of config properties ...
        Configuration dbHistoryConfig =
                config.subset(DatabaseHistory.CONFIGURATION_FIELD_PREFIX_STRING, false)
                        .edit()
                        .withDefault(DatabaseHistory.NAME, getLogicalName() + "-dbhistory")
                        .withDefault(
                                KafkaDatabaseHistory.INTERNAL_CONNECTOR_CLASS,
                                connectorClass.getName())
                        .withDefault(KafkaDatabaseHistory.INTERNAL_CONNECTOR_ID, logicalName)
                        .build();

        DatabaseHistoryListener listener =
                config.getBoolean(JMX_METRICS_ENABLED)

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set database.history to a valid implementation available on the classpath, e.g. io.debezium.relational.history.MemoryDatabaseHistory (or FileDatabaseHistory with its storage path configured)
2. Check the class name for typos and confirm the containing jar is in the plugin dependencies
3. Inspect the root cause logged by config.getInstance for ClassNotFound/linkage errors
4. Align the property with the SeaTunnel CDC connector's supported history implementations

Example fix

// before
database.history = "io.debezium.relational.history.StoreDatabaseHistory"
// after
database.history = "io.debezium.relational.history.MemoryDatabaseHistory"

String cls = config.getString(HistorizedRelationalDatabaseConnectorConfig.DATABASE_HISTORY);
try {
    Class.forName(cls).asSubclass(DatabaseHistory.class);
} catch (Throwable t) {
    throw new IllegalStateException("database.history class unavailable: " + cls, t);
}

try {
    engineConfig.getDatabaseHistory();
} catch (ConnectException e) {
    LOG.error("Fix database.history property: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Setting database.history (HistorizedRelationalDatabaseConnectorConfig.DATABASE_HISTORY) to a class name that is not on the classpath, is misspelled, or doesn't implement DatabaseHistory; omitting the property without a viable default.

Common situations: Typos or wrong package in the database.history value; shaded/uber-jar missing Debezium history classes due to dependency exclusion; copying a Flink CDC config into SeaTunnel with incompatible class names.

Related errors

• Data change record shouldn't use READ operation, the the rec
• The table changes should only have one element
• Unknown table change type:
• should not call here, error
• Failed to authenticate to the MySQL database at <hostname>:<

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