Version: 0.7 (Latest)

Troubleshooting

Common issues encountered during MigratorXpress migrations and how to resolve them.

Connection Issues

Cannot connect to source database

Symptoms: Connection timeout or authentication error when MigratorXpress starts.

Solutions:

Verify that the credentials file is valid JSON and that the --source_db_auth_id matches a key in the file. An auth ID that is not in the file stops the run with exit code 10; the message lists the available entry names.
Check the entry format. For auth_mode "classic", info must contain non-empty username, password, server, database and an integer port (for example 1521, not "1521"), and nothing else (except lib_dir for Oracle). An invalid entry stops the run at startup with exit code 10 (INVALID_AUTH_ENTRY, AUTH_MODE_NOT_SUPPORTED or INVALID_CONNECTION_STRING) and a message naming the entry and the key. See Authentication modes.
Values are used literally: $env{...} references are not expanded.
Test connectivity independently (e.g., psql, sqlplus, sqlcmd) before running MigratorXpress.
Confirm the server hostname, port, and database name are correct (Oracle: service name).

A connection failure stops the run with a CONNECTION FAILED summary and exit code 12.

# Test Oracle connectivity (host:port/service_name)
sqlplus migrator@//oracle-host:1521/ORCLPDB1

# Test PostgreSQL connectivity
psql -h pg-host -p 5432 -U migrator -d analytics

# Test SQL Server connectivity
sqlcmd -S sql-host,1433 -U migrator -d target_db

Migration database not accessible

Symptoms: Error connecting to the migration tracking database or error creating tables.

Solutions:

The migration tracking database must be SQL Server (ds_type: "mssql") or PostgreSQL (ds_type: "postgres").
Verify the --migration_db_auth_id references a valid entry of one of these types in the credentials file.
The connecting user must be able to create and alter tables in the tracking database (and own the public schema on PostgreSQL, see PostgreSQL as Migration Tracking).
On SQL Server, a classic entry uses SQL Server authentication, which needs mixed-mode authentication. Otherwise use a trusted entry (integrated authentication).

SQL Server example:

-- Grant CREATE TABLE permission
USE migration_log;
GRANT CREATE TABLE TO your_migration_user;
GRANT ALTER ON SCHEMA::dbo TO your_migration_user;
GRANT INSERT, UPDATE, DELETE, SELECT ON SCHEMA::dbo TO your_migration_user;

PostgreSQL Issues

Connection refused

Symptoms: could not connect to server: Connection refused

Solutions:

Verify PostgreSQL is running:
```
systemctl status postgresql
```
Check that pg_hba.conf allows connections from your IP address. Add a line such as:
```
host    all    all    10.0.0.0/8    md5
```
Then reload the configuration:
```
sudo systemctl reload postgresql
```
Check firewall rules:
```
sudo ufw allow 5432/tcp
```
Confirm PostgreSQL is listening on the correct interface. Check listen_addresses in postgresql.conf:
```
listen_addresses = '*'
```

Authentication failed

Symptoms: FATAL: password authentication failed for user

Solutions:

Verify the username and password are correct.
Check the password encryption method in pg_hba.conf (md5 vs scram-sha-256).

Confirm the user exists:

SELECT * FROM pg_user WHERE usename = 'your_user';

Check that the password in the credentials file is exactly the database password (it is used as written; JSON escaping rules apply to \ and ").

Oracle Issues

ORA-12154: TNS could not resolve connect identifier

Symptoms: Connection fails with TNS resolution error.

Solutions:

Verify that the database value in the credentials file is the service name registered with the listener (lsnrctl services). MigratorXpress connects with host:port/service_name; SIDs and TNS aliases are not supported.
Try using the IP address instead of the hostname.
Confirm the Oracle listener is running:
```
lsnrctl status
```

ORA-28000: account is locked

Symptoms: Login fails because the Oracle account is locked.

Solutions:

Unlock the account as a DBA:

ALTER USER your_username ACCOUNT UNLOCK;

Check if the account was locked due to too many failed login attempts. Review the account profile:

SELECT profile FROM dba_users WHERE username = 'YOUR_USER';
SELECT resource_name, limit FROM dba_profiles WHERE profile = 'DEFAULT' AND resource_name = 'FAILED_LOGIN_ATTEMPTS';

Thick mode library not found

Symptoms: Error loading Oracle client libraries, typically DPI-1047: Cannot locate a 64-bit Oracle Client library.

Solutions:

Verify the lib_dir path in the credentials file points to a valid Oracle Instant Client directory.
Confirm the Instant Client version matches the platform (64-bit required).
Check file permissions on the Instant Client directory.

On Linux, set LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_8:$LD_LIBRARY_PATH

On Linux, you may also need libaio:

sudo apt-get install libaio1    # Debian/Ubuntu
sudo yum install libaio         # RHEL/CentOS

SQL Server Issues

Symptoms: Login failed for user 'username'

Solutions:

For a classic entry, confirm SQL Server is configured for SQL Server Authentication (mixed mode), not Windows Authentication only, or switch to a trusted entry (integrated authentication).
Verify the username and password are correct.

Check that the user exists and is not disabled:

SELECT name, is_disabled FROM sys.sql_logins WHERE name = 'your_user';

Check for IP restrictions or firewall rules blocking the connection.

Integrated authentication fails on Linux

Symptoms: a trusted entry (or a connection string with Integrated Security=true) cannot log in from Linux.

Solutions:

Check that the account running MigratorXpress has a valid Kerberos ticket for the whole run (klist; renew with kinit, or kinit -kt with a keytab).
Check that /etc/krb5.conf declares the realm and its KDC.
Give the server by its fully qualified domain name, not an IP address or a CNAME alias.
Check that the service principal MSSQLSvc/<fqdn>:<port> is registered for the SQL Server service account.
Install the system GSSAPI library (libgssapi_krb5), needed by FastTransfer.

ODBC entry rejected at startup

Symptoms: an odbc entry stops the run with exit code 10.

Solutions:

odbc is accepted for a SQL Server source or tracking database only, never for the target.
Install the ODBC prerequisites, which are not bundled: on Linux the unixODBC driver manager (libodbc.so.2), on every platform the Microsoft ODBC Driver 18 for SQL Server, and declare the DSN (/etc/odbc.ini, ~/.odbc.ini, or the Windows ODBC Data Source Administrator).

Cannot define PRIMARY KEY constraint on nullable column

Symptoms: copy_pk fails on a SQL Server target with Cannot define PRIMARY KEY constraint on nullable column.

Solutions:

Up to 0.7.2, every column of a PostgreSQL source was created nullable on the target. Since 0.7.3 the source NOT NULL is kept: recreate the tables (--task_list translate create with --drop_tables_if_exists true, then reload them) before running copy_pk.

Symptoms: Cannot open database "dbname" requested by the login. The login failed.

Solutions:

Verify the database name in the credentials file is spelled correctly (case-sensitive on Linux-hosted SQL Server).

Confirm the user has access to the database:

USE your_database;
SELECT * FROM sys.database_principals WHERE name = 'your_user';

Check the database is online:

SELECT name, state_desc FROM sys.databases WHERE name = 'your_database';

Netezza Issues

Connection refused

Symptoms: could not connect to server: Connection refused on port 5480.

Solutions:

Verify the Netezza appliance is powered on and the NPS service is running.
Confirm the correct port (default: 5480, not 5432).
Check network connectivity:
```
telnet nz-host 5480
```
Verify firewall rules allow traffic to port 5480.

Authentication failed

Symptoms: FATAL: password authentication failed

Solutions:

Verify the username and password.

Confirm the user exists in the Netezza system:

SELECT username FROM _v_user WHERE username = 'YOUR_USER';

Check that the user has access to the target database:

SELECT * FROM _v_object_data WHERE objname = 'YOUR_DATABASE';

General Tips

Exit codes

Code	Meaning
`0`	Every table succeeded every task (differences found by `diff` do not fail a table)
`1`	Other error (migration error, invalid `--migration_db_mode`, unexpected exception)
`2`	Command-line parsing error (missing required argument, invalid value)
`10`	Configuration error detected at startup: invalid auth entry, auth ID not found, unsupported target or tracking database type, unsupported source/target pair, `copy_*` with a Netezza source, `copy_fk` with a PostgreSQL target, ODBC problem
`12`	Database connection failure (source, target, or tracking database)
`13`	License error (invalid, expired, not yet active, or trial expired)
`20`	Validation error: invalid task options, invalid `--fk_mode`, `--target_db_name` not matching the target auth entry
`40`	Some tables failed a task: fix the cause and `--resume <run_id>`
`41`	Every table failed a task

See Exit Codes for the details.

"the following arguments are required"

--auth, --source_db_auth_id, --target_db_auth_id and --migration_db_auth_id are mandatory for every run, including --resume. Only --upgrade_migdb relaxes the source and target arguments. --source_db_name and --target_db_name are optional since 0.7.2.

Target database name mismatch

Symptoms: the run stops with exit code 20 and --target_db_name '...' does not match the database '...' of the target auth entry.

--target_db_name must match the database of the target auth entry (case-insensitively for SQL Server, exactly for PostgreSQL). Remove the option, or fix the auth entry. --source_db_name is ignored: the source database is always the one of the source auth entry.

Task list rejected

incorrect task sequence means the task combination is not one of the accepted sequences (for example translate transfer without create). Either 'task_list' or 'resume' should be given means both or neither were given. See Migration Tasks. These errors exit with code 20.

Unsupported combination rejected at startup

Exit code 10 with UNSUPPORTED_SOURCE_TARGET_PAIR (Netezza to PostgreSQL), CONSTRAINT_COPY_UNSUPPORTED_SOURCE (copy_* with a Netezza source) or COPY_FK_UNSUPPORTED_TARGET (copy_fk, or --task_list all, with a PostgreSQL target). Remove the unsupported tasks from --task_list, for example --task_list translate create transfer diff copy_pk copy_ak for a PostgreSQL target. See Compatibility.

Table not created with a PostgreSQL target

SQL Server GEOGRAPHY / GEOMETRY columns and PostgreSQL ARRAY / user-defined columns cannot be translated for a PostgreSQL target: translate fails for the table, and create reports it as failed without creating it. Exclude these tables (--exclude_tables) and migrate them separately.

`--drop_tables_if_exists` value rejected

--drop_tables_if_exists accepts true/yes/1 (or no value) and false/no/0. Any other value is rejected by the argument parser (exit code 2). Up to 0.7.1, any value enabled the option, including false.

Tracking database on the old schema

On the first 0.7 run against a tracking database created by 0.6.x, MigratorXpress logs metadata DB is on the old schema; upgrading in place and upgrades it. You can also run the upgrade separately with --upgrade_migdb (see Upgrading the tracking database). Back up the tracking database first.

License errors

The license is searched in this order: MIGRATORXPRESS_LICENSE environment variable, --license, --license_file, ~/.migratorxpress/license.lic (Linux/macOS) or %APPDATA%\MigratorXpress\license.lic (Windows), then ./license.lic. Without a license, a 30-day trial counted from the build date of the binary applies. A license that is found but invalid or expired stops the run with exit code 13.

Enable debug logging

Set --log_level DEBUG to capture detailed diagnostics including SQL statements, FastTransfer commands, and connection details:

./MigratorXpress --auth ./credentials.json \
  --log_level DEBUG \
  --log_dir /tmp/mig_debug \
  ...

Check the log file

Every migration run creates a log file named mig_YYYYMMDD_HHMMSS_<run_id>.log in --log_dir (default: current directory). Review the full log for error context that may not appear in the terminal summary.

Resume after failure

If a migration fails partway through, or the RUN SUMMARY lists failed tables (exit code 40 or 41), use --resume with the run ID to process only the jobs that are not DONE rather than starting over. The run ID is part of the log file name:

./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7

Verify FastTransfer binary

MigratorXpress uses the FastTransfer found in --fasttransfer_dir_path, or in the engine/ directory next to its binary when the flag is omitted. FastTransfer 0.15.0 or later is required. Confirm the binary is executable and check its version (printed in the banner when run without arguments):

ls -la ./FastTransfer_linux-x64_v0.15.0/
./FastTransfer_linux-x64_v0.15.0/FastTransfer

Connection Issues​

Cannot connect to source database​

Migration database not accessible​

PostgreSQL Issues​

Connection refused​

Authentication failed​

Oracle Issues​

ORA-12154: TNS could not resolve connect identifier​

ORA-28000: account is locked​

Thick mode library not found​

SQL Server Issues​

Login failed for user​

Integrated authentication fails on Linux​

ODBC entry rejected at startup​

Cannot define PRIMARY KEY constraint on nullable column​

Cannot open database requested by the login​

Netezza Issues​

Connection refused​

Authentication failed​

General Tips​

Exit codes​

"the following arguments are required"​

Target database name mismatch​

Task list rejected​

Unsupported combination rejected at startup​

Table not created with a PostgreSQL target​

--drop_tables_if_exists value rejected​

Tracking database on the old schema​

License errors​

Enable debug logging​

Check the log file​

Resume after failure​

Verify FastTransfer binary​

See Also​

Connection Issues

Cannot connect to source database

Migration database not accessible

PostgreSQL Issues

Connection refused

Authentication failed

Oracle Issues

ORA-12154: TNS could not resolve connect identifier

ORA-28000: account is locked

Thick mode library not found

SQL Server Issues

Login failed for user

Integrated authentication fails on Linux

ODBC entry rejected at startup

Cannot define PRIMARY KEY constraint on nullable column

Cannot open database requested by the login

Netezza Issues

Connection refused

Authentication failed

General Tips

Exit codes

"the following arguments are required"

Target database name mismatch

Task list rejected

Unsupported combination rejected at startup

Table not created with a PostgreSQL target

`--drop_tables_if_exists` value rejected

Tracking database on the old schema

License errors

Enable debug logging

Check the log file

Resume after failure

Verify FastTransfer binary

See Also