Skip to content

Common errors

This page lists the most common problems and what they mean.

Backup refused: target size exceeds limit

Reason

  • Planned backup size exceeds backup.maxTotalMb

Fix

  • Increase backup.maxTotalMb
  • Or use configs-only mode (do not use --full)
  • Or narrow the target (plugin:Name instead of plugins)

Backup lock is busy

Reason

  • Another operation is running (backup, restore, reload, scheduler)

Fix

  • Wait and retry
  • Reduce scheduler frequency
  • Avoid running restore while scheduler is active

Cannot diff backups with missing meta.json

Reason

  • Backup folder is incomplete or corrupted

Fix

  • Delete the broken backup folder
  • Recreate a new backup

Restore refused: meta.json invalid

Reason

  • Metadata is malformed or missing required fields

Fix

  • Recreate a new backup
  • Do not edit meta.json manually

Restore refused: payload hash mismatch

Reason

  • Payload file differs from meta.json sha256

Fix

  • Backup is corrupted, do not restore it
  • Recreate a new backup

Restore refused: unsafe path

Reason

  • Traversal or absolute path detected

Fix

  • Do not attempt to restore unsafe paths
  • Verify backup integrity

Locked files were skipped (FULL mode)

Reason

  • OS locked files prevented copying

Fix

  • Check:

backups//locked-files.txt

  • Exclude DB extensions and rerun FULL backup if needed