GTR FAQ

10 Troubleshooting

9 min read

Firebird not found

The Firebird 5.x line on the Setup tab shows Not configured or Not found: <path>, or Auto-Detect Firebird reports Firebird 5.x not found.

  1. Check that Firebird is installed.
  2. Look for fbclient.dll in the Firebird installation folder.
  3. Click Auto-Detect Firebird on the Setup tab.
  4. If detection fails, enter the path in the Configuration tab and click Save .env.

No .env file found

The Setup tab shows No .env file found. The file .env is missing in C:\ProgramData\GTR mbH\Firebird-Management, for example because someone deleted it.

  1. Click Auto-Detect Firebird. The tool creates a new .env file with default settings and the Firebird paths it found.
  2. In the Configuration tab, enter the SYSDBA password from the setup as FB50_PASSWD. See Credentials.
  3. Click Save .env.

No Firebird 2.5 server

The operation stops with one of these messages:

  • No Firebird 2.5 server is running on this computer (port 3050). Vacuum Firebird 2.5 Database needs the Firebird 2.5 server. Start the Firebird 2.5 service, or migrate the database to Firebird 5 instead.
  • No Firebird 2.5 server is running on this computer (port 3050), and firebird25_embed.zip is missing in the program folder. Run the GTR Firebird setup again. It installs the file.

A migration without a Firebird 2.5 server is described in Migration without a Firebird 2.5 server.

Database file not found

The tool cannot find the database file.

  1. Check the path.
  2. Check that you have access rights for the file.
  3. Select the file with Browse….

Client DLL not found

The message reads No Firebird client DLL found (FB50_CLIENT, FB25_CLIENT). Neither client library in .env exists.

  1. Check the status lines on the Setup tab.
  2. Check FB25_CLIENT and FB50_CLIENT in the Configuration tab.
  3. Typical locations:
    • Firebird 2.5: C:\Program Files\Firebird\Firebird_25\bin\fbclient.dll
    • Firebird 5: C:\Program Files\Firebird\Firebird_50\fbclient.dll

One of the two files is enough. See One client for all operations.

Authentication failed

Firebird rejects the user name or the password.

  1. For Firebird 5, check FB50_PASSWD in the Configuration tab. It must contain the SYSDBA password from the setup. See Credentials.
  2. For Firebird 2.5, check FB25_PASSWD, or FB_PASSWD if FB25_PASSWD is not set.
  3. Check the user names in FB_USER, FB25_USER and FB50_USER.
  4. For a Firebird 5 server on another computer, the user must exist in Legacy_UserManager on that server. See Requirements on the server.

In the TCP/IP mode, the tool uses User and Password of the box instead of .env. Check both fields.

Database is in use

Another program or service uses the database.

  1. Close all programs that use the database.
  2. Stop all services that connect to the database.
  3. Wait a moment and start the operation again.

Operation takes a long time

The duration depends on the size of the database:

  • a few seconds for small databases (under 100 MB)
  • several minutes for medium databases (100 MB to 1 GB)
  • an hour or more for very large databases (over 1 GB)

In the modes Local Database and Remote Database (file access via network share) the Log Output panel shows the progress. The TCP/IP mode shows no progress messages. The log shows the size of the backup after the backup step.

Another operation is running

A warning with the title Operation running appears:

  • Another operation is running. The tool runs one job at a time. Wait until the running operation, detection or connection test has finished.
  • An operation is running. Close the window after it has finished. The window does not close during a database operation. Wait for the completion message.

Target database cannot be created

A TCP/IP migration without Overwrite an existing database at the target stops before the backup with this message:

The Firebird server <server> cannot create <path>: <Firebird message>. If a database exists there, tick "Overwrite an existing database at the target" or enter another path. Otherwise the Firebird service needs write access to the folder, and DatabaseAccess in firebird.conf must allow it.

The tool tried to create the target database and failed. The Firebird message gives the reason:

  • A message such as File exists means that a file exists at the target path. Windows reports it in the language of the server, for example Die Datei ist vorhanden.
  • Permission denied or a refusal by DatabaseAccess means that the folder is not usable. See Server cannot create a database in the folder.

The tool has transferred no data and keeps no backup file. A file at the target path stays unchanged.

  1. Check the path in the box Firebird 5 target. It must not point to the Firebird 2.5 database.
  2. If the existing database at the target may be replaced, tick Overwrite an existing database at the target. Otherwise enter another path.
  3. Start the operation again.

The check can leave an empty database at the target path if the tool cannot delete it. The error message then names this file. Delete it on the server before you start again.

The restore can still fail with this error if a file appears at the target path while the backup runs. The tool then keeps the backup in a folder firebird_<random> in the Windows temp folder of this computer.

Server cannot open the database for writing

A TCP/IP operation stops at the start of the backup with this message:

The Firebird server <server> cannot open <database> for writing: no permission for read-write access to database <database>; ...

Firebird opens a database for reading and writing, also for a backup. The account of the Firebird service has read access to the file, but no write access. The tool has transferred no data, and the database stays unchanged.

On a Linux server with Firebird installed directly, the service runs as the user firebird. A file that root copied to the server belongs to root. Give the file to firebird:

chown firebird:firebird /opt/firebird-data/PROFDIA.FDB
chmod 660 /opt/firebird-data/PROFDIA.FDB

Do not use chmod 777. On Windows, give the account of the Firebird service the Modify permission on the file. Then start the operation again.

See Firebird 2.5 installed directly on Linux.

Server cannot create a database in the folder

A TCP/IP operation stops before the backup with this message:

The Firebird server <server> cannot create a database in <folder>: <Firebird message>. The Firebird service needs write access to this folder, and DatabaseAccess in firebird.conf must allow it.

The tool tried to create a small test database in the folder of the database. The Firebird message gives the reason, for example Permission denied or No such file or directory. The tool has transferred no data, and the database stays unchanged.

  1. Grant the account of the Firebird service write access to the folder. On Linux this is usually the user firebird. Write access to the database file alone is not enough. See Firebird 2.5 installed directly on Linux.
  2. Check that DatabaseAccess in firebird.conf of the server allows the folder.
  3. Check that the folder exists on the server.
  4. Start the operation again.

Firebird 2.5 empties the database file and stops responding if a restore cannot replace the database. For this reason the tool checks the folder first. Such a hang can still occur when someone runs gbak by hand. Restart the Firebird service to end it.

Client already loaded

An operation or the connection test fails with this message:

Firebird client <path> is already loaded; this program cannot switch to <new path> while it runs. Restart Firebird Management.

The program loads one Firebird client library when the first connection starts. It keeps this library until the program ends. The error appears if FB50_CLIENT or FB25_CLIENT changed while the program runs, for example after Auto-Detect Firebird or Save .env.

  1. Close Firebird Management.
  2. Start it again.

TCP/IP restore fails on the server

The backup succeeds and the restore fails. Possible causes:

  • The Firebird server may not write to the target folder. Grant the Firebird service account write access to the folder. The tool checks the folder before the backup. For an alias it skips this check in some cases, see Checks before the backup.
  • DatabaseAccess in firebird.conf of the server does not allow the path.
  • The path is the host path of a Docker container. Enter the path inside the container. See Firebird in a Docker container.
  • The server has not enough free space.

The error message names the kept backup file. For a vacuum, it also names the database that may be incomplete. Restore that database from the backup file with gbak before anyone works with it again.

Copy-back to the network share fails

The operation on the local copy succeeded, but the tool cannot replace the database on the share.

  1. Check that you have write access to the folder on the share.
  2. Check that no program holds the database on the share open.
  3. Check the free space on the share.

The database on the share keeps its previous content. If a file must be renamed by hand, the log names it. The error message names the temporary folder with the processed database. Copy it to the share by hand, or start the operation again.

Cannot write the database INI file

The GTR DB Config tab shows Cannot write <file>. Start Firebird Management as administrator and try again.

  1. Close Firebird Management.
  2. Right-click Manage Firebird Databases in the Start menu and select Run as administrator. Windows 11 lists it under More.
  3. Load the file again and repeat the save.

The file stays unchanged after this error.

DB Config connection test fails

Test connection on the GTR DB Config tab reports Connection failed: followed by the Firebird error. Check the following:

Symptom in the error messageCheck
The server is unreachable, or the connection is refusedServer and Port. The Firebird 5 server must run, and a firewall must allow the port.
The user name or password is not definedUsername and Password. The user must exist in Legacy_UserManager on the Firebird 5 server.
The database file is not found or cannot be openedDatabase. Enter the path as the Firebird 5 server sees it. In a Docker container, enter the path inside the container.

A result with ODS 11.2 means that the connection reached a Firebird 2.5 database. Check Port and Database.

The driver check reports one of these messages:

  • Driver: <path> not found or not a DLL. The file in DriverPath does not exist. For the 32-bit driver, run the GTR Firebird setup on this computer.
  • Driver: <path> is x64, but x86 is selected. The library does not match the selected Driver. Select the other choice, or correct DriverPath.

Further help

If a problem is not covered here:

  1. Read the error messages in the Log Output panel.
  2. Check the settings in the Configuration tab.
  3. Check that the Firebird servers run.
  4. Ask your system administrator for the database credentials.

Graph View

Backlinks