`gbak: ERROR` … `gbak:Exiting before completion due to errors`

What it means

gbak backs up through the Firebird engine, table by table and row by row. The first record or page the engine cannot read stops the whole backup, and the message before Exiting before completion names the reason: often an internal Firebird consistency check, a wrong page type or an I/O error. Everything after that point is missing from the backup, even if it is intact in the file.

Options that get further

-g (no garbage collection): the backup does not try to clean up old record versions, which can touch damaged records it would not otherwise read.
-ig (ignore checksums): skips the page checksums older versions write.
gfix -mend -full -ignore before the backup: marks the damaged records so gbak skips them.
-v shows which table was being read when it stopped.

The full order of steps:

First: make a copy, and work only on the copy

Stop the Firebird server, or at least make sure nothing is connected to the database. Then copy the file, together with any .delta file next to it (an nbackup lock) and the secondary files of a multi-file database. A copy taken while the server writes to the file is inconsistent, and every repair attempt changes the file it runs on. If the disk itself is failing, copy the file to another disk before anything else.

Then: try Firebird’s own tools

These come with every Firebird installation and often get a database back as a whole: indexes, triggers, users and all. On the copy:

gfix -v -full -n copy.fdb            # validate, report only
gfix -mend -full -ignore copy.fdb    # let gbak skip damaged records
gbak -b -v -ig -g copy.fdb copy.fbk  # back up: no checksums, no GC
gbak -c -v copy.fbk restored.fdb     # restore into a new database

Add -user SYSDBA -password ... as your server needs. If gbak -b completes, the restored database is the result: check the row counts of the important tables. gfix -mend throws away the records it cannot read, so compare with the original before you rely on the restored copy.

If gbak still fails: get the data out with fbrescue

fbrescue reads the database file directly, without the Firebird engine, and exports every row it can read. It does not stop at the first damaged record or page, and it never writes to the file. Download the single binary for your system from Releases (Windows, Linux, macOS; nothing to install).

fbrescue scan copy.fdb                               # what is damaged, by table
fbrescue export copy.fdb --out rescued --format sql  # schema.sql + INSERTs per table

--format csv and --format jsonl are there too. Rows that could not be read are listed in rescued/_errors.jsonl with the page and the reason, and the exit status is 2 when anything was left out. To load the result into a new database:

isql -ch UTF8 -i rescued/schema.sql new.fdb
isql -ch UTF8 -i rescued/CUSTOMERS.sql new.fdb  # and so on for each table

If you would like help, open an issue and attach the output of fbrescue report copy.fdb: it describes the damage without any of your data, and with table and column names replaced by numbers.

fbrescue reads without the engine, so a damaged record or page costs that record or page, not the rest of the backup. Each table is exported to its own file, and _errors.jsonl says what was left out and why.

gbak: ERROR … gbak:Exiting before completion due to errors