Troubleshooting

Most replication problems show up as rising lag, a broken table or a repeating error. Start with twincommit status and /status, or ask the MCP server’s explain_error tool. Then use the table below.

Symptom	Likely cause	Fix
Lag rises, then drops suddenly	A large source transaction buffering until commit	Normal. Check open_transactions; raise max_txn_memory_bytes if spilling is slow.
Lag rises steadily	Target apply slower than change rate	Raise batch.max_rows, check target indexes and locks, size up the warehouse on lakehouse targets
log file not found at start	Checkpoint older than the oldest log the source still has	Increase archive retention; re-snapshot affected tables
Table broken after a release	ALTER TABLE or non-logged load	Re-snapshot the table
SQL0551N / ORA-01031	Missing privilege on the source	Run twincommit check and apply the printed fix
invalid byte sequence for encoding "UTF8": 0x00	NUL byte in source character data (PostgreSQL target)	Clean the source value, or exclude the column
Duplicate key errors on target	Another process writes to the target table	Make TwinCommit the only writer
Kafka consumers see aborted data	Consumers use read_uncommitted	Set isolation.level=read_committed

Collecting diagnostics

twincommit status -config pipeline.yaml -json > status.json
curl -s localhost:9108/metrics > metrics.txt
journalctl -u twincommit@prod-db2 --since "1 hour ago" > twincommit.log

Attach these to your support ticket. Add twincommit logdump -brief output only if support asks for it, because it can contain row data.