Skip to main content

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:

  1. Verify that the credentials file is valid JSON and that the --source_db_auth_id matches a key in the file.
  2. Test connectivity independently (e.g., psql, sqlplus, sqlcmd) before running MigratorXpress.
  3. Check that environment variables referenced with $env{VAR_NAME} are set in the current shell session.
  4. Confirm the server hostname, port, and database name are correct.
# Verify environment variables are set
echo $ORA_USER
echo $ORA_PASSWORD

# Test Oracle connectivity
sqlplus $ORA_USER/$ORA_PASSWORD@//oracle-host:1521/ORCL

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

# Test SQL Server connectivity
sqlcmd -S sql-host,1433 -U $MSSQL_USER -P $MSSQL_PASSWORD -d target_db

Migration database not accessible​

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

Solutions:

  1. The migration database must be SQL Server -- other database types are not supported for migration tracking.
  2. Enable mixed-mode authentication (SQL Server Authentication + Windows Authentication) on the SQL Server instance.
  3. The connecting user must have CREATE TABLE permissions in the target database.
  4. Verify the --migration_db_auth_id references a valid mssql entry in the credentials file.
-- 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';
  • If using $env{PG_PASSWORD}, verify the environment variable does not contain trailing whitespace or special characters that need escaping.

Oracle Issues​

ORA-12154: TNS could not resolve connect identifier​

Symptoms: Connection fails with TNS resolution error.

Solutions:

  • Verify the service name or SID in the credentials file matches the Oracle listener configuration.
  • Check tnsnames.ora if using TNS aliases.
  • Try using the IP address instead of the hostname.
  • Confirm the Oracle listener is running: 
    lsnrctl status
  • If using Oracle thick mode, verify that $ORACLE_HOME/network/admin/tnsnames.ora or $TNS_ADMIN/tnsnames.ora is correctly configured.

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​

Login failed for user​

Symptoms: Login failed for user 'username'

Solutions:

  • Confirm SQL Server is configured for SQL Server Authentication (mixed mode), not Windows Authentication only.
  • 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.

Cannot open database requested by the login​

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.
  • Confirm the ODBC driver for Netezza is installed on the MigratorXpress host.

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​

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 migratorxpress_YYYYMMDD_HHMMSS_<run_id>.log. Review the full log for error context that may not appear in the terminal summary.

Resume after failure​

If a migration fails partway through, use --resume to continue from the last successful table rather than starting over:

./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --resume

Verify FastTransfer binary​

Confirm the FastTransfer binary is executable and the path is correct:

ls -la ./FastTransfer_linux-x64_v0.12.4/
./FastTransfer_linux-x64_v0.12.4/FastTransfer --version

See Also​

Copyright © 2026 Architecture & Performance.