Troubleshooting

Troubleshooting

Read the last error, not the first. The pipeline stops at the earliest problem, so the final message is the one to act on. In every stop case below the target is unchanged — there is no half-migrated state to clean up, and re-running after a fix is safe.

Messages are listed by their stable message code; the UI may show them translated (Turkish today), but the code identifies the message regardless of language.

When the run stops

Code	It means	What to do
error.noTablesToCopy	Source and target share no tables	Wrong database selected, or the target schema was never created
error.sourceOnlyTable	The source has a table the target does not	Decide whether that table still matters. If it was dropped on purpose, tick allow tables missing from target
error.columnNotSynthesizable	A target column is NOT NULL, missing from the source, and has no safe default	Fix the target schema — the engine will not invent a value for that type
error.preflightNulls	Source rows carry NULLs into a NOT NULL target column	Fix the data or the schema. Allow schema risk only moves the failure into the copy
error.preflightLength	Values longer than the target column allows	Widen the target column
error.collationMismatch	The target's collation is not the expected one	Recreate the target database with the right collation — it cannot be altered in place
error.rowCountMismatch	A table's source and target row counts differ after copy	The run rolled back; nothing was committed. Investigate the table it names
error.orphanRows	The source contains child rows whose parent is missing	Clean the source. Nothing was written — verification runs before commit
error.zeroRows	No rows were copied at all	The source is empty or the wrong database was selected
error.targetDbNameMissing	The target connection has no database name	Fill in the target database field

Operational errors

Symptom	Cause	Fix
permission denied to set parameter "session_replication_role"	The PostgreSQL user is not superuser	Constraint-trigger suspension needs superuser; run with one
permission denied to create database	Missing CREATEDB	Grant it, or create the target database yourself first
out of shared memory (late in a large run)	Lock budget exhausted — one transaction locks every table	Raise max_locks_per_transaction (512+) on the target and restart it
A copy error naming table.column (row N, type T)	A source value the target type rejects	The message pinpoints table, column and row; inspect that value
Browser doesn't open on start	Headless machine or no default browser	The app is still up — open http://localhost:5099 yourself
The window closes instantly on launch / address already in use	Port 5099 is taken. Since v0.1.1, a second copy of the app simply opens the running UI and exits; only an unrelated app holding 5099 is an error	Find the occupant (netstat -ano on Windows, look for :5099), close it, relaunch

Warnings worth reading

• warn.truncateCascade — TRUNCATE CASCADE also emptied dependent tables. Those with no source counterpart stay empty; if your application seeds them at boot, start it once after migrating.
• warn.sourceOnlyTable — data in that table is not migrated. Make sure that is what you meant.
• warn.collationMismatchAllowed / warn.preflightAllowed — you asked the tool to proceed past a check; the consequences it warned about are now yours.