{"record":{"id":"a012a927d3218dda","repo":"apache/seatunnel","slug":"failed-to-start-replication-stream-at-lsn","errorCode":null,"errorMessage":"Failed to start replication stream at <lsn>","messagePattern":"Failed to start replication stream at <lsn>","errorType":"exception","errorClass":"DebeziumException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-opengauss/src/main/java/io/debezium/connector/postgresql/connection/PostgresReplicationConnection.java","lineNumber":415,"sourceCode":"        Lsn lsn = offset;\n        if (LOGGER.isDebugEnabled()) {\n            LOGGER.debug(\"starting streaming from LSN '{}'\", lsn);\n        }\n\n        final int maxRetries = connectorConfig.maxRetries();\n        final Duration delay = connectorConfig.retryDelay();\n        int tryCount = 0;\n        while (true) {\n            try {\n                return createReplicationStream(lsn, walPosition);\n            } catch (Exception e) {\n                String message = \"Failed to start replication stream at \" + lsn;\n                if (++tryCount > maxRetries) {\n                    if (e.getMessage().matches(\".*replication slot .* is active.*\")) {\n                        message +=\n                                \"; when setting up multiple connectors for the same database host, please make sure to use a distinct replication slot name for each.\";\n                    }\n                    throw new DebeziumException(message, e);\n                } else {\n                    LOGGER.warn(\n                            message + \", waiting for {} ms and retrying, attempt number {} over {}\",\n                            delay,\n                            tryCount,\n                            maxRetries);\n                    final Metronome metronome = Metronome.sleeper(delay, Clock.SYSTEM);\n                    metronome.pause();\n                }\n            }\n        }\n    }\n\n    @Override\n    public void initConnection() throws SQLException, InterruptedException {\n        // See https://www.postgresql.org/docs/current/logical-replication-quick-setup.html\n        // For pgoutput specifically, the publication must be created before the slot.\n        initPublication();","sourceCodeStart":397,"sourceCodeEnd":433,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-opengauss/src/main/java/io/debezium/connector/postgresql/connection/PostgresReplicationConnection.java#L397-L433","documentation":"Thrown by startStreaming when START_REPLICATION fails repeatedly and the retry count exceeds maxRetries. Each attempt waits a delay and logs a warning; once exhausted, a DebeziumException is thrown with the target LSN. If the underlying error message matches 'replication slot ... is active', an extra hint about using distinct slot names per connector is appended.","triggerScenarios":"START_REPLICATION <lsn> SLOT <slot> fails on each retry: another process holds the slot (slot is active), the requested LSN is no longer available (WAL removed), network interruptions persist, or the server rejects the slot/LSN combination.","commonSituations":"Two connectors (or a leftover zombie walreceiver backend) using the same replication slot name on the same host; connecting to a standby that was promoted/restored causing LSN mismatch; aggressive wal_keep_size/replication slot retention removing needed WAL; long network outages exceeding the retry budget.","solutions":["If the message says the slot is active, find and terminate the competing backend: SELECT pg_terminate_backend(pid) FROM pg_stat_replication / pg_stat_activity where the slot is in use, and ensure each connector uses a unique slot.name.","Check pg_replication_slots for active_pid/conflicting slot state and kill stale walreceiver sessions left by crashed clients.","Verify the start LSN is still available (pg_waldump / pg_replication_slots confirmed_flush_lsn vs min WAL retained); increase wal_keep_size or re-snapshot if WAL was purged.","Increase the retry count/delay in connector configuration if failures are transient (network blips).","Confirm connectivity to the primary and that the slot still exists; recreate the slot and restart with a fresh snapshot if it was dropped."],"exampleFix":"// before: two connectors sharing one slot -> 'replication slot my_slot is active'\n\"slot.name\": \"my_slot\"  // used by connector A and B\n// after\n\"slot.name\": \"connector_a_slot\"  // unique per connector instance","handlingStrategy":"retry","validationCode":"-- ensure the slot is free and WAL is retained before starting\nSELECT slot_name, active, active_pid, restart_lsn, confirmed_flush_lsn\nFROM pg_replication_slots WHERE slot_name = 'my_slot';\nSELECT pg_current_wal_lsn(), pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn))\nFROM pg_replication_slots WHERE slot_name = 'my_slot';","typeGuard":null,"tryCatchPattern":"try {\n    stream = connection.createReplicationStream(startLsn);\n} catch (DebeziumException e) {\n    if (e.getMessage().contains(\"replication slot\") && e.getMessage().contains(\"is active\")) {\n        // terminate competing backend (pg_terminate_backend(active_pid)) or use a unique slot name\n    } else if (e.getMessage().startsWith(\"Failed to start replication stream\")) {\n        // check WAL retention / LSN availability, possibly re-snapshot\n    } else {\n        throw e;\n    }\n}","preventionTips":["Assign a unique slot.name to every connector instance against the same database host.","Monitor pg_replication_slots.active/active_pid and alert on unexpected holders.","Set adequate wal_keep_size / max_slot_wal_keep_size so the start LSN's WAL is not purged.","Configure generous retry delays for flaky networks; clean up crashed clients' walreceiver backends."],"tags":["postgresql","cdc","replication","wal","retry"],"backgroundTag":"address-already-in-use","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}