apache/seatunnel · critical · SeaTunnelRuntimeException

CREATE_REPLICATION_CONNECTION_FAILED

CREATE_REPLICATION_CONNECTION_FAILED

Error message

${taskContext}

What it means

PostgresObjectUtils.createReplicationConnection gives up after exhausting all connection retries when opening a PostgreSQL logical replication connection for CDC. It wraps the failure in SeaTunnelRuntimeException with code CREATE_REPLICATION_CONNECTION_FAILED and the task context as message. Underlying causes (auth, network, slot issues) are only visible in the logged retry warnings.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-postgres/src/main/java/io/debezium/connector/postgresql/PostgresObjectUtils.java:121

                    throw new ConnectException(ex);
                }

                log.warn(
                        "Error connecting to server; will attempt retry {} of {} after {} "
                                + "seconds. Exception message: {}",
                        retryCount,
                        maxRetries,
                        retryDelay.getSeconds(),
                        ex.getMessage());
                try {
                    metronome.pause();
                } catch (InterruptedException e) {
                    log.warn("Connection retry sleep interrupted by exception: " + e);
                    Thread.currentThread().interrupt();
                }
            }
        }
        throw new SeaTunnelRuntimeException(CREATE_REPLICATION_CONNECTION_FAILED, "" + taskContext);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the JDBC/replication host, port and credentials are correct and the database is reachable (e.g. psql connection test).
2. Ensure the user has REPLICATION privilege and pg_hba.conf allows replication connections from the client host.
3. Check the slot is not already actively used by another replication client; drop or reuse it.
4. Inspect the retry WARN logs just before this error for the underlying SQLException.

Example fix

// before
url = "jdbc:postgresql://db-host:5432/mydb"
user = "app_user"           // no REPLICATION privilege
// after
url = "jdbc:postgresql://db-host:5432/mydb"
user = "replication_user"   // WITH REPLICATION, or superuser

pg_isready -h db-host -p 5432 && psql "postgres://replication_user@db-host:5432/mydb" -c 'SELECT 1;'

try {
  startCdcSource(postgresConfig);
} catch (SeaTunnelRuntimeException e) {
  if (e.getSeaTunnelErrorCode() == CREATE_REPLICATION_CONNECTION_FAILED) {
    // alert ops: replication connectivity/slot/privilege problem
  }
}

When it happens

Trigger: Called during Postgres CDC source initialization when establishing the logical replication connection (e.g. wal2json/decoder connection) fails repeatedly until the retry loop is exhausted.

Common situations: Wrong hostname/port or firewall blocking the replication port; invalid dbz username/password; user lacks REPLICATION privilege; slot already in use by another consumer; pg_hba.conf rejecting replication connections; database unreachable.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Couldn't get timestamp utils from underlying connection
• The DB connection is not a valid replication connection
• received unexpected exception will perform keep alive
• Error getting current Lsn/txId ${e.getMessage()}
• JDBC connection fails to commit: ${e.getMessage()}

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