BackupAlly Documentação 880e6e8

Troubleshooting

Soluções para problemas comuns do BackupAlly.

Erros de Conexão

MySQL: Connection Refused 

Error: Connection refused (os error 111)

Causas:

  • MySQL não está rodando
  • Porta incorreta
  • Firewall bloqueando

Soluções:

# Verificar se MySQL está rodando
sudo systemctl status mysql

# Testar conexão
mysql -h localhost -u backup -p

# Verificar porta
netstat -tlnp | grep 3306

Container em mais de uma rede 

Container 'mysql' esta em 2 redes (interna=192.0.2.10, publica=192.0.2.20)
— impossivel escolher automaticamente.

Causa: host = "docker:mysql" sem dizer qual rede usar. Separar rede de aplicação e rede de dados é prática comum, então isso é frequente.

Solução: declarar a rede.

host = "docker:mysql/interna"

Para descobrir as redes do container:

docker inspect mysql --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}={{$v.IPAddress}} {{end}}'

Em versões anteriores à 0.17.0 este caso não dava erro: os IPs eram concatenados e a falha aparecia depois como failed to lookup address information: Name does not resolve, parecendo problema de DNS. Se você vê essa mensagem, atualize antes de investigar a rede.

PostgreSQL: Authentication Failed 

Error: password authentication failed

Soluções:

  1. Verifique credenciais:
psql -h localhost -U backup -d postgres
  1. Verifique pg_hba.conf:
host    all    backup    127.0.0.1/32    scram-sha-256
  1. Reload config:
sudo systemctl reload postgresql

MongoDB: Connection Timeout 

Error: connection timed out

Soluções:

# Verificar se MongoDB está rodando
sudo systemctl status mongod

# Testar conexão
mongosh --eval "db.adminCommand('ping')"

Erros de Permissão

Permission Denied 

Error: Permission denied (os error 13)

Soluções:

  1. Execute como root:
sudo backupally backup --target website
  1. Ou ajuste permissões do diretório:
sudo chown -R backupally:backupally /var/www/html

MySQL: Access Denied 

Error: Access denied for user 'backup'@'localhost'

Solução:

GRANT SELECT, SHOW DATABASES, LOCK TABLES ON *.* TO 'backup'@'localhost';
FLUSH PRIVILEGES;

Erros de Storage

S3: Access Denied 

Error: Access Denied

Causas:

  • Credenciais inválidas
  • Permissões insuficientes
  • Bucket não existe

Soluções:

  1. Verifique credenciais:
backupally secrets get aws_access_key
  1. Verifique permissões IAM:
{
  "Effect": "Allow",
  "Action": [
    "s3:PutObject",
    "s3:GetObject",
    "s3:ListBucket",
    "s3:DeleteObject"
  ],
  "Resource": [
    "arn:aws:s3:::bucket-name",
    "arn:aws:s3:::bucket-name/*"
  ]
}

B2: Invalid Authorization 

Error: Invalid authorization token

Solução:

Regenere a Application Key no console B2 e atualize:

backupally secrets set b2_key_id "novo-key-id"
backupally secrets set b2_app_key "novo-app-key"

Espaço em Disco Insuficiente 

Error: No space left on device

Soluções:

  1. Verifique espaço:
df -h /var/lib/backupally
df -h /backup
  1. Limpe temporários (desde a 0.33.0 o padrão é /var/lib/backupally/temp, não mais /tmp/backupally; a 0.35.0 já apaga isso sozinha em todo run bem-sucedido — ver nota abaixo):
rm -rf /var/lib/backupally/temp/*
  1. Ajuste diretório temporário:
[global]
default_temp_path = "/var/tmp/backupally"

Temporário de run não sobrava mais depois de sucesso (0.35.0). Antes, todo run bem-sucedido deixava <default_temp_path>/<backup_id> para trás (~3x o tamanho do backup, entre .tar e .ally) — o cleanup() do executor era um no-op. Corrigido: o caminho de erro já não era afetado. Em panic (o binário de release roda com panic = 'abort') o temporário ainda pode sobrar, e cleanup --residues não o reconhece.

Backup PARCIAL: alguns databases ficaram de fora 

Backup PARCIAL: 2 de 48 item(ns) falharam

Com on_error = "continue", um item que falha não derruba o run — os demais seguem. O backup existe, mas está incompleto.

Onde ver o que faltou:

# status e duração do run
backupally history

# nome e erro de cada item que falhou
backupally history --show <backup_id> --full

# ou direto no log
grep 'Failed to process database\|Backup PARCIAL' /var/log/backupally/backupally.log.$(date +%F)

O run aparece no histórico como ⚠️ Partial, e o task run sai com código ≠ 0 — dá para detectar em automação sem ler o texto.

Causas frequentes: timeout no upload de um database grande, falha transitória de autorização no storage, ou permissão faltando em um database específico.

Versões anteriores à 0.19.0 registravam o run como "In Progress" para sempre e não guardavam quais itens falharam — a informação só aparecia no terminal de quem rodou na mão.

Upload falhou após 3 tentativas 

upload falhou apos 3 tentativas: ... operation timed out

Upload e verificação repetem 3 vezes com backoff (2s → 4s) antes de desistir. Esgotar as três tentativas indica problema persistente, não soluço:

  • Arquivo grande + limite de banda: [network] max_mbps estica a duração do upload. Um database de vários GB com limite baixo pode estourar o tempo de forma consistente — aumente o limite ou reduza o escopo daquela task
  • Credencial do storage: confira com backupally storage check
  • Rede do servidor até o storage: teste fora do BackupAlly

Upload de arquivo grande para o B2

Sintoma (antes da 0.24.0): todo upload acima de certo tamanho falhava perto de 60 segundos, nas três tentativas, enquanto arquivos menores passavam.

Causa: o timeout era o tempo total da requisição. O que decidia era tamanho ÷ taxa contra 60s, e a taxa varia ao longo da madrugada.

Solução: atualizar. Desde a 0.24.0 o timeout é dimensionado pelo tamanho (piso 60s, teto 6h) e arquivos acima de 100 MB sobem em partes, cada uma com seu próprio retry.

Verificação reprovando um upload que terminou (0.24.0): a B2 devolve contentSha1 = "none" para arquivo enviado em partes. Corrigido na 0.24.1.

Upload em partes interrompido no meio (processo morto entre o início e o fim do large file): as partes já enviadas ocupam cota e não aparecem na listagem normal do bucket. Para encontrá-las:

backupally cleanup --residues --dry-run   # relata
backupally cleanup --residues             # remove

O relatório diz quantos destinos remotos foram consultados, para "nenhum resíduo remoto" não ter a mesma cara de "não consegui perguntar".

Backup não começa: "servidor sobrecarregado" 

servidor sobrecarregado: load average (1m) em 3.10 (limite: 1.50)

Um limite do [guard] foi atingido (desde 0.26.0). A mensagem diz o recurso, o medido e o limite. Ou a máquina está de fato no limite e o backup deve esperar, ou o limite está apertado demais — ajuste em `[guard]`. Sem a seção, não há limite nenhum.

Erros de Criptografia

Invalid Key 

Error: Failed to decrypt: Invalid key

Causa: Tentando restaurar com chave diferente.

Solução:

  1. Verifique fingerprint do backup:
backupally inspect backup.ally
  1. Use a chave correta:
backupally restore \
  --target mysql-prod \
  --snapshot snap_xxx \
  --key /path/to/correct-key.pem

Key Not Found 

Error: Key file not found

Solução:

# Verificar se chave existe
ls -la /etc/backupally/keys/

# Regenerar se necessário
backupally keys generate --name default --set-default

Restore de arquivos devolveu `chunk_.data`

O backup foi feito com versão anterior à 0.28.0. Até lá o fileset era guardado como blocos sem caminho nem ordem, e não há como remontar os arquivos a partir deles. Atualize e refaça o backup; a partir da 0.28.0 o restore devolve a árvore original abaixo de --path.

Restore pede chave num backup sem cifra

Corrigido na 0.28.0. Antes, o extrator carregava a chave antes de ler o header e falhava se /etc/backupally/keys/default.key não existisse, mesmo com o backup em claro. Se a chave está em outro caminho, o restore agora lê [crypto] default_key_ref do --config.

Restore falha com "truncado no bloco N"

O .ally acabou antes do bloco final (0.29.0+). Ou o upload não terminou, ou o download foi parcial. Confira o tamanho no storage (storage check) e baixe de novo; no B2, cleanup --residues mostra uploads em partes inacabados.

Restore falha com "Unsupported envelope version: 2"

O binário que está restaurando é anterior à 0.29.0 e o backup foi feito pela 0.29.0 ou mais nova. Atualize: sudo backupally self-update.

Erros de Scheduler

Task Não Executa

Verificações:

  1. Task está habilitada?
backupally task list
  1. Scheduler está rodando?
sudo systemctl status backupally-scheduler
  1. Condição não atendida?
# Ver logs
sudo journalctl -u backupally-scheduler -f
  1. Fora da janela?

Verifique [window] na task.

  1. Rodou em outro horário?

O cron é interpretado em UTC quando a task não declara timezone. Num servidor em -03, schedule = "30 3 * * *" dispara 00:30 no horário local. O scheduler informa o próximo disparo nos dois fusos ao carregar a task:

Adicionando tarefa agendada: mysql (30 3 * * * [UTC])
  — proxima execucao: 2026-08-24 03:30:00 +00:00 (UTC) / 2026-08-24 03:30:00 UTC

Ver Agendamento.

  1. Mudou o config e não reiniciou?

O scheduler lê as tasks na inicialização. Alterou schedule, timezone ou qualquer campo da task: reinicie o serviço.

  1. A condição em when está sendo entendida?

Condição que não casa com nenhum formato conhecido é tratada como comando de shell — e a task não roda se a saída for diferente de "0". Um erro de digitação tem o mesmo efeito de uma condição que deu falso. A partir da 0.22.0 isso gera aviso no log:

Condicao 'lodavg() < 2' nao casa com nenhum formato conhecido ...

Hot Reload Não Funciona

Solução:

# Forçar reload
sudo systemctl reload backupally-scheduler

# Ou reiniciar
sudo systemctl restart backupally-scheduler

self-update adiado: "backup em andamento"

Desde a 0.26.0 o self-update não troca o binário enquanto um backup roda: ele adia e informa qual task está executando e há quanto tempo. Rode de novo quando terminar. --force ignora a guarda; --check não é afetado.

Se a mensagem persistir sem nenhum backup rodando, a trava /var/lib/backupally/run.lock ficou de um processo que morreu — ela é removida sozinha ao detectar que o processo não existe mais. Confirme com ps que não há backupally executando.

Tasks editadas não têm efeito no agendamento

Antes da 0.23.0 o scheduler carregava a config uma vez e nunca relia o disco. task run <id> lia o arquivo fresco, então o teste manual passava e o agendado seguia com a config antiga. Desde a 0.23.0 o scheduler detecta arquivo editado, criado ou removido em pipeline/ e recarrega sozinho, registrando Config de tasks mudou no disco — recarregando no log. Se estiver numa versão anterior, reinicie o serviço após editar.

Erros de Rede

Timeout 

Error: Connection timed out

Soluções:

  1. Aumente timeout:
[network]
timeout_seconds = 600
  1. Verifique conectividade:
curl -v https://s3.amazonaws.com

SSL Certificate Error 

Error: certificate verify failed

Soluções:

  1. Atualize certificados:
sudo apt update && sudo apt install ca-certificates
  1. Para MinIO self-signed:
[[storage]]
driver = "minio"
verify_ssl = false

Logs e Debug

Habilitar Debug 

backupally --log-level debug backup --target mysql-prod

Ver Logs do Scheduler 

sudo journalctl -u backupally-scheduler -f

Arquivo de Log 

tail -f /var/log/backupally/backupally.log

journalctl não mostra nada ao filtrar por backupally 

sudo journalctl -t backupally -f

Se vier vazio num servidor instalado antes da 0.27.1, a unit não tem SyslogIdentifier e o journald identifica as linhas pelo nome do processo. Rode uma vez:

sudo backupally install-service   # reescreve a unit e faz daemon-reload

Histórico sumiu depois de um reboot

Antes da 0.25.0 o histórico ficava em /tmp/backupally/logs, apagado no reboot. Desde então fica em /var/lib/backupally/logs, com migração automática na primeira execução. Se o processo não tiver permissão em /var/lib (rodando como usuário comum), ele cai para o diretório antigo e avisa que é volátil — nesse caso, rode como root ou dê permissão ao diretório.

Verificar Configuração 

backupally config verify
backupally task validate mysql-prod --deep

Obter Ajuda

Se o problema persistir:

  1. Verifique logs com --log-level debug
  2. Consulte a documentação
  3. Abra issue no repositório
By Borlot.com.br on 23/08/2026

Tags

troubleshooting erros debug