Could not register for streaming with metadata in messages…

Error message

Could not register for streaming with metadata in messages, falling back to messages without metadata

What it means

createReplicationStream first tries to start streaming with metadata options (e.g. wal2json include-types style metadata or pgoutput messages with metadata). If PostgreSQL rejects an unknown option (old wal2json plugin), it logs this warning and falls back to streaming without metadata, re-initializing a temporary slot if needed.

Solutions

Upgrade the wal2json extension on the server to a version supporting the requested options.
Explicitly set the expected plugin/config (plugin.name=pgoutput with publication) to avoid legacy wal2json paths.
Ignore safely: the connector auto-falls back; verify downstream decode still works with metadata-less messages.
If on RDS, confirm the supported plugin version and options for your engine version.

Example fix

// before
{"plugin.name": "wal2json", "slot.stream.params": "include-types=true"} // old wal2json
// after
// upgrade wal2json, or:
// {"plugin.name": "pgoutput", "publication.name": "dbz_publication"}

Defensive patterns

Strategy: fallback

Validate before calling

SELECT extversion FROM pg_extension WHERE extname='wal2json'; -- require recent version, or use pgoutput

Prevention

Install latest wal2json or prefer pgoutput with a publication.
Match plugin.name config to the actually installed plugin.
Test option support with a START_REPLICATION probe on staging.

When it happens

Trigger: START_REPLICATION with messageDecoder.optionsWithMetadata raises PSQLException matching 'ERROR: option .* is unknown' — server has an older wal2json or a plugin not supporting the requested option.

Common situations: Old wal2json versions lacking format-version/include options; RDS-managed Postgres with restricted plugins; switching plugin types (wal2json vs pgoutput) without updating connector config.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-opengauss/src/main/java/io/debezium/connector/postgresql/connection/PostgresReplicationConnection.java:545

                // re-init the slot after a failed start of slot, as this
                // may have closed the slot
                if (useTemporarySlot()) {
                    initReplicationSlot();
                }

                s =
                        startPgReplicationStream(
                                startLsn,
                                plugin.forceRds()
                                        ? messageDecoder::optionsWithoutMetadata
                                        : messageDecoder::optionsWithMetadata);
                messageDecoder.setContainsMetadata(plugin.forceRds() ? false : true);
            }
        } catch (PSQLException e) {
            if (e.getMessage().matches("(?s)ERROR: option .* is unknown.*")) {
                // It is possible we are connecting to an old wal2json plug-in
                LOGGER.warn(
                        "Could not register for streaming with metadata in messages, falling back to messages without metadata");

                // re-init the slot after a failed start of slot, as this
                // may have closed the slot
                if (useTemporarySlot()) {
                    initReplicationSlot();
                }

                s = startPgReplicationStream(startLsn, messageDecoder::optionsWithoutMetadata);
                messageDecoder.setContainsMetadata(false);
            } else if (e.getMessage()
                    .matches("(?s)ERROR: requested WAL segment .* has already been removed.*")) {
                LOGGER.error("Cannot rewind to last processed WAL position", e);
                throw new ConnectException(
                        "The offset to start reading from has been removed from the database write-ahead log. Create a new snapshot and consider setting of PostgreSQL parameter wal_keep_segments = 0.");
            } else {
                throw e;
            }

View on GitHub (pinned to cf67b549a7)