Skip to main content

Troubleshooting

This guide helps you resolve common issues you might encounter when installing or running FastTransfer.

Installation Issues​

Linux: Permission Denied​

Problem: When trying to run FastTransfer, you get "Permission denied" error.

Solution:

chmod +x FastTransfer

This command grants execution rights to the FastTransfer binary.

Why this happens: Downloaded files on Linux don't have execute permissions by default for security reasons.

License File Not Found​

Problem: FastTransfer reports it cannot find the license file.

Solutions:

  1. Verify the license file exists in the same directory as the executable:

    ls -la FastTransfer*

  2. Check file permissions (must be readable):

    Right-click on FastTransfer.lic → Properties → Security tab → Ensure your user has Read permissions

  3. Use the --license parameter to specify the path explicitly:

    ./FastTransfer --license "/path/to/FastTransfer.lic" ...

See also: License Management for detailed license configuration options.

Missing Dependencies (Linux)​

Problem: FastTransfer fails to start with library errors like "error while loading shared libraries".

Solution:

Install the required dependencies for your distribution:

sudo apt-get update
sudo apt-get install libicu-dev

Why this happens: Some minimal Linux distributions don't include all required system libraries by default.

Network and Connectivity Issues​

Firewall and Network​

Problem: FastTransfer cannot connect to source or target databases.

Solution:

Ensure your firewall allows outbound connections to your database servers on the required ports:

DatabaseDefault Port
SQL Server1433
PostgreSQL5432
MySQL3306
Oracle1521
SAP HANA30015
Teradata1025
Netezza5480
ClickHouse9000

Common fixes:

  1. Test connectivity manually:

    # Test if port is open (replace HOST and PORT)
    telnet database.example.com 5432

  2. Check firewall rules:

    # Check Windows Firewall
    Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*FastTransfer*"}

  3. Verify database server allows connections from your IP

Connection Timeout​

Problem: Connections to databases time out.

Solutions:

  1. Check network latency:

    ping database.example.com

  2. Increase timeout settings (if your database is far or has high latency):

    • Check your database connection string for timeout parameters
    • Ensure the database server isn't overloaded

  3. Verify VPN or proxy settings if connecting to databases behind a VPN

Performance Issues​

Slow Transfer Speed​

Problem: Data transfer is slower than expected.

Solutions:

  1. Increase batch size:

    --batchsize 100000

  2. Enable parallel processing:

    --parallelmethod Random --paralleldegree 4

  3. Check network bandwidth between source and target

  4. Verify database performance:

    • Check if source database is under heavy load
    • Ensure target database has sufficient resources

  5. Use appropriate connection types:

    • For SQL Server: Use msbulk for target
    • For PostgreSQL: Use pgcopy for target
    • For Oracle: Use orabulk or orabdp for source

High Memory Usage​

Problem: FastTransfer consumes excessive memory.

Solutions:

  1. Reduce batch size:

    --batchsize 10000

  2. Limit parallel degree:

    --paralleldegree 2

  3. Monitor system resources and adjust accordingly

Data Transfer Issues​

Data Type Mismatch​

Problem: Transfer fails with data type conversion errors.

Solutions:

  1. Use custom query to cast incompatible types:

    --sourcequery "SELECT id, CAST(date_column AS VARCHAR) as date_column FROM table"

  2. Check column mapping with --mapmethod Name or --mapmethod Position

  3. Review compatibility matrix in the documentation for your source/target combination

Character Encoding Issues​

Problem: Special characters appear corrupted after transfer.

Solutions:

  1. Verify source and target database encodings match or are compatible

  2. Check column collations (especially for SQL Server)

  3. Use Unicode data types when transferring international characters

Duplicate Key Errors​

Problem: Transfer fails with primary key or unique constraint violations.

Solutions:

  1. Use --loadmode Truncate to clear target table before loading:

    --loadmode Truncate

  2. Filter source data to exclude duplicates:

    --sourcequery "SELECT DISTINCT * FROM table"

  3. Disable constraints temporarily on target (handle with care)

Command Line Issues​

Command Not Found (PATH Issues)​

Problem: Shell reports "command not found" when trying to run FastTransfer.

Solutions:

  1. Use full path or relative path:

    # Instead of
    FastTransfer --version

    # Use
    ./FastTransfer --version

  2. Add to PATH (optional):

    $env:PATH += ";C:\Tools\FastTransfer"

Parameter Parsing Errors​

Problem: FastTransfer doesn't recognize parameters or reports syntax errors.

Solutions:

  1. Quote parameter values containing spaces or special characters:

    --sourceserver "my server.example.com"
    --sourcequery "SELECT * FROM table WHERE date > '2024-01-01'"

  2. Escape special characters in your shell:

    --sourcequery "SELECT * FROM table WHERE col = 'value'"

  3. Use the Command Wizard to generate correct syntax

Getting More Help​

If your issue isn't covered here:

1. Check the Logs​

Set log level to debug for detailed information:

--loglevel Debug

2. Review Documentation​

3. Contact Support​

  • Email: support@arpe.io
  • Support Portal: support.arpe.io
  • Include in your request:
    • FastTransfer version (--version)
    • Operating system and version
    • Source and target database types
    • Error messages or log excerpts
    • Command being executed (redact sensitive information)

4. Community Resources​

  • GitHub Issues: Report bugs or request features
  • Documentation: Check for updates and new guides
  • Release Notes: Review known issues in your version

Reporting Bugs​

When reporting bugs, please include:

  1. Reproduction steps: Clear steps to reproduce the issue
  2. Expected behavior: What you expected to happen
  3. Actual behavior: What actually happened
  4. Environment details:
    • Operating system
    • FastTransfer version
    • Database versions
  5. Logs: Relevant log excerpts (with --loglevel Debug)
  6. Command: The command you ran (redact credentials)

This information helps us diagnose and fix issues quickly.

Copyright © 2026 Architecture & Performance. Built with Docusaurus.