apache/seatunnel · error · SeaTunnelException

PostgreSQL-CDC schema evolution requires 'decoding.plugin.na

Error message

PostgreSQL-CDC schema evolution requires 'decoding.plugin.name = pgoutput' because PostgreSQL RELATION messages provide the changed schema.

What it means

SeaTunnel PostgreSQL CDC throws this during startup validation when schema evolution is enabled (`schema-changes.enabled = true`) but the logical decoding plugin is not `pgoutput`. Only pgoutput emits PostgreSQL RELATION messages carrying the changed table schema, which the schema-evolution machinery needs to resolve DDL changes; other plugins (e.g. decoderbufs, wal2json) cannot supply that information.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/postgres/source/PostgresIncrementalSource.java:184

                options.getOptional(PostgresIncrementalSourceOptions.SLOT_NAME)
                        .map(String::trim)
                        .filter(name -> !name.isEmpty());
        if (!slotName.isPresent()) {
            throw new SeaTunnelException(
                    String.format(
                            "PostgreSQL-CDC startup.mode '%s' requires an explicit '%s' option.",
                            StartupMode.COMMITTED_OFFSET,
                            PostgresIncrementalSourceOptions.SLOT_NAME.key()));
        }
    }

    private void validateSchemaEvolutionOptions(ReadonlyConfig options) {
        if (options.get(SourceOptions.SCHEMA_CHANGES_ENABLED)
                && !"pgoutput"
                        .equalsIgnoreCase(
                                options.get(
                                        PostgresIncrementalSourceOptions.DECODING_PLUGIN_NAME))) {
            throw new SeaTunnelException(
                    String.format(
                            "PostgreSQL-CDC schema evolution requires '%s = pgoutput' because PostgreSQL RELATION messages provide the changed schema.",
                            PostgresIncrementalSourceOptions.DECODING_PLUGIN_NAME.key()));
        }
    }

    private Map<TableId, Struct> tableChanges() {
        JdbcSourceConfig jdbcSourceConfig = configFactory.create(0);
        PostgresDialect dialect =
                new PostgresDialect(
                        (PostgresSourceConfigFactory) configFactory,
                        catalogTables,
                        requireReplicaIdentityFull);
        List<TableId> discoverTables = dialect.discoverDataCollections(jdbcSourceConfig);
        SchemaNameAdjuster adjuster = SchemaNameAdjuster.create();
        ConnectTableChangeSerializer connectTableChangeSerializer =
                new ConnectTableChangeSerializer(adjuster);
        try (JdbcConnection jdbcConnection = dialect.openJdbcConnection(jdbcSourceConfig)) {

View on GitHub (pinned to cf67b549a7)

Solutions

Set `decoding.plugin.name = pgoutput` in the source options.
Or disable schema evolution (`schema-changes.enabled = false`) if you do not need DDL tracking.
Ensure the replication user has sufficient privileges (pg_monitor / replication role) since pgoutput requires a logical replication slot.

Example fix

// before
PostgresIncrementalSource.<String>builder()
    .schemaChangesEnabled(true)
    .decodingPluginName("decoderbufs")
    .build();
// after
PostgresIncrementalSource.<String>builder()
    .schemaChangesEnabled(true)
    .decodingPluginName("pgoutput")
    .build();

Defensive patterns

Strategy: validation

Validate before calling

if (schemaChangesEnabled && !"pgoutput".equalsIgnoreCase(decodingPluginName)) {
    throw new IllegalArgumentException("schema-changes.enabled=true requires decoding.plugin.name=pgoutput");
}

Prevention

Always pair schema-changes.enabled=true with decoding.plugin.name=pgoutput
Centralize CDC source config building in one helper that enforces this invariant
Document the pairing requirement in your job templates

When it happens

Trigger: Calling PostgresIncrementalSource builder with `.schemaChangesEnabled(true)` (or config `schema-changes.enabled=true`) while `decoding.plugin.name` is unset (defaults to decoderbufs) or set to anything other than `pgoutput` (case-insensitive check).

Common situations: Users copying older CDC configs that used decoderbufs; enabling schema evolution on clusters where pgoutput is the default but the option was explicitly overridden; forgetting that slot creation with non-pgoutput plugins cannot convey schema.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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