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

O que significa

O gbak faz o backup através do motor do Firebird, tabela por tabela e linha por linha. O primeiro registro ou página que o motor não consegue ler interrompe o backup inteiro, e a mensagem antes de Exiting before completion diz o motivo: muitas vezes um internal Firebird consistency check, uma página do tipo errado ou um erro de E/S. Tudo depois desse ponto falta no backup, mesmo que esteja intacto no arquivo.

Opções que vão mais longe

-g (sem coleta de lixo): o backup não tenta limpar versões antigas de registros, o que pode tocar em registros danificados que ele de outro modo não leria.
-ig (ignorar checksums): pula os checksums de página que versões antigas gravam.
gfix -mend -full -ignore antes do backup: marca os registros danificados para que o gbak os pule.
-v mostra qual tabela estava sendo lida quando ele parou.

A ordem completa de passos:

Primeiro: faça uma cópia e trabalhe só na cópia

Pare o servidor Firebird ou, no mínimo, garanta que nada esteja conectado ao banco. Depois copie o arquivo, junto com o arquivo .delta ao lado dele, se houver (um bloqueio do nbackup), e os arquivos secundários de um banco multiarquivo. Uma cópia feita enquanto o servidor grava no arquivo fica inconsistente, e toda tentativa de reparo altera o arquivo em que é executada. Se o próprio disco está falhando, copie o arquivo para outro disco antes de qualquer coisa.

Depois: tente as ferramentas do próprio Firebird

Elas vêm com toda instalação do Firebird e muitas vezes recuperam o banco inteiro: índices, triggers, usuários e tudo mais. Na cópia:

gfix -v -full -n copia.fdb              # valida, só relata
gfix -mend -full -ignore copia.fdb      # faz o gbak pular registros danificados
gbak -b -v -ig -g copia.fdb copia.fbk   # backup: sem checksums, sem coleta de lixo
gbak -c -v copia.fbk restaurado.fdb     # restaura em um banco novo

Acrescente -user SYSDBA -password ... conforme o seu servidor exigir. Se o gbak -b terminar, o banco restaurado é o resultado: confira a quantidade de linhas das tabelas importantes. O gfix -mend descarta os registros que não consegue ler, então compare com o original antes de confiar na cópia restaurada.

Se o gbak ainda falhar: extraia os dados com o fbrescue

O fbrescue é uma ferramenta gratuita e de código aberto (licença MIT) para bancos Firebird 2.5–5.0. Ele lê o arquivo do banco diretamente, sem o motor do Firebird, e exporta todas as linhas que consegue ler. Não para no primeiro registro ou página danificada e nunca grava no arquivo. Baixe o executável para o seu sistema em Releases: Windows, Linux, macOS; não precisa instalar nada.

fbrescue scan copia.fdb                                # o que está danificado, por tabela
fbrescue export copia.fdb --out resgate --format sql   # schema.sql + INSERTs por tabela

Também existem --format csv e --format jsonl. As linhas que não puderam ser lidas ficam listadas em resgate/_errors.jsonl, com a página e o motivo, e o código de saída é 2 quando algo ficou de fora. Para carregar o resultado em um banco novo:

isql -ch UTF8 -i resgate/schema.sql novo.fdb
isql -ch UTF8 -i resgate/CLIENTES.sql novo.fdb  # e assim por diante, para cada tabela

Se o texto sair ilegível, o banco provavelmente guarda texto em CHARACTER SET NONE: informe a codificação real, em geral --charset WIN1252 ou --charset ISO8859_1 em programas brasileiros.

Se quiser ajuda, abra uma issue e anexe a saída de fbrescue report copia.fdb: ela descreve o dano sem nenhum dos seus dados, e com os nomes de tabelas e colunas trocados por números. Pode escrever em português.

O fbrescue lê sem o motor, então um registro ou página danificada custa aquele registro ou página, não o resto do backup. Cada tabela é exportada para o seu próprio arquivo, e o _errors.jsonl diz o que ficou de fora e por quê.

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