MOLT Replicator Troubleshooting

This page describes common issues that can occur while using and suggests ways to troubleshoot those issues.

Some of the contents of this page are specific to your source database (PostgreSQL, MySQL, or Oracle). Select your source using the dropdown at the top right of this page.

Forward replication issues

Performance troubleshooting

If MOLT Replicator appears hung or performs poorly:

Enable trace logging with -vv to get more visibility into the replicator’s state and behavior.

If MOLT Replicator is in an unknown, hung, or erroneous state, collect performance profiles to include with support tickets. Replace {host} and {metrics-port} with your Replicator host and the port specified by :

curl '{host}:{metrics-port}/debug/pprof/trace?seconds=15' > trace.out
curl '{host}:{metrics-port}/debug/pprof/profile?seconds=15' > profile.out
curl '{host}:{metrics-port}/debug/pprof/goroutine?seconds=15' > gr.out
curl '{host}:{metrics-port}/debug/pprof/heap?seconds=15' > heap.out

Monitor lag metrics and adjust performance parameters as needed.

The instructions in this section are specific to PostgreSQL source databases. To see instructions for other source database types, select a different option from the dropdown at the top right of this page.

Unable to create publication or slot

This error occurs when logical replication is not supported.Resolution: If you are connected to a replica, connect to the primary instance instead. Replicas cannot create or manage logical replication slots or publications.Verify that the source database supports logical replication by checking the wal_level parameter on PostgreSQL:

SHOW wal_level;

If wal_level is not set to logical, update it and restart PostgreSQL:

ALTER SYSTEM SET wal_level = 'logical';

Replication slot already exists

ERROR: replication slot "molt_slot" already exists

Resolution: Either create a new slot with a different name, or drop the existing slot to start fresh:

SELECT pg_drop_replication_slot('molt_slot');

Dropping a replication slot can be destructive and delete data that is not yet replicated. Only use this if you want to restart replication from the current position.

Publication does not exist

run CREATE PUBLICATION molt_fetch FOR ALL TABLES;

Resolution: Create the publication on the source database. Ensure you also create the replication slot:

CREATE PUBLICATION molt_publication FOR ALL TABLES;
SELECT pg_create_logical_replication_slot('molt_slot', 'pgoutput');

Could not connect to PostgreSQL

could not connect to source database: failed to connect to `user=migration_user database=migration_db`

Resolution: Verify the connection details including user, host, port, and database name. Ensure the database name in your --sourceConn connection string matches exactly where you created the publication and slot. Verify you’re connecting to the same host and port where you ran the CREATE PUBLICATION and SELECT pg_create_logical_replication_slot() commands. Check if TLS certificates need to be included in the connection URI.

Wrong replication slot name

run SELECT pg_create_logical_replication_slot('molt_slot', 'pgoutput'); in source database

Resolution: or verify the correct slot name:

SELECT pg_create_logical_replication_slot('molt_slot', 'pgoutput');

Schema drift errors

Indicates source and target schemas are mismatched:

WARNING: schema drift detected in "database"."table" at payload object offset 0: unexpected columns: column_name

Resolution: Align schemas or .

Apply flow failures

Apply flow failures occur when the target database encounters error conditions such as unique constraint violations, target database being unavailable, or incorrect data (missing or extraneous columns) during apply operations:

WARNING: warning during tryCommit: ERROR: duplicate key value violates unique constraint
ERROR: maximum number of retries (10) exceeded

Resolution: Check target database constraints and connection stability. MOLT Replicator will log warnings for each retry attempt. If you see warnings but no final error, the apply succeeded after retrying. If all retry attempts are exhausted, Replicator will surface a final error and restart the apply loop to continue processing.

Failback issues

If the changefeed shows connection errors in SHOW CHANGEFEED JOB:

Connection refused

transient error: Post "https://replicator-host:30004/migration_db/migration_schema": dial tcp [::1]:30004: connect: connection refused

This indicates that Replicator is down, the webhook URL is incorrect, or the port is misconfigured.Resolution: Verify that MOLT Replicator is running on the port specified in the changefeed INTO configuration. Confirm the host and port are correct.

Incorrect schema path errors

This error occurs when the webhook URL path does not match the target database schema naming convention:

transient error: 400 Bad Request: unknown schema:

The webhook URL path is specified in the INTO clause when you create the changefeed. For example: webhook-https://replicator-host:30004/database/schema.Resolution: Verify the webhook path format matches your target database type:

PostgreSQL targets should use /database/schema format. For example, webhook-https://replicator-host:30004/migration_db/migration_schema.

For details on configuring the webhook sink URI, refer to .

GC threshold error

batch timestamp * must be after replica GC threshold

This indicates starting from an invalid cursor that has been garbage collected. Resolution: Double-check the cursor to ensure it represents a valid range that has not been garbage collected, or extend the GC TTL on the source CockroachDB cluster:

ALTER DATABASE defaultdb CONFIGURE ZONE USING gc.ttlseconds = {gc_ttl_in_seconds};

Duplicated data re-application

This occurs when resuming a changefeed from a cursor causes excessive data duplication. Resolution: Clear the staging database to prevent duplication. This deletes all checkpoints and buffered data, so use with caution:

DROP DATABASE _replicator;

For more targeted cleanup, delete mutations from specific staging tables:

DELETE FROM _replicator.employees WHERE true;

Migration Considerations

MOLT Tools

Common Migration Approaches

Third-Party Migration Tools

Migrate Data Types

MOLT Replicator Troubleshooting

Forward replication issues

Performance troubleshooting

Unable to create publication or slot

Replication slot already exists

Publication does not exist

Could not connect to PostgreSQL

Wrong replication slot name

Schema drift errors

Apply flow failures

Failback issues

Connection refused

Incorrect schema path errors

GC threshold error

Duplicated data re-application

See also

​Forward replication issues

Performance troubleshooting

Unable to create publication or slot

Replication slot already exists

Publication does not exist

Could not connect to PostgreSQL

Wrong replication slot name

Schema drift errors

Apply flow failures

​Failback issues

Connection refused

Incorrect schema path errors

GC threshold error

Duplicated data re-application

​See also

Forward replication issues

Failback issues

See also