Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

FAQ

For job failures, upload errors, or restore errors, start here; if unresolved see Contact support.

Backup failed but the failing step is unclear—what now?

See whether the job stopped at local packaging, upload, encryption, or MySQL export, then cross-check task results and common states and config. Common checks:

  • Whether backup source paths are correct
  • Default config directory exists and all three TOML files are tuned for your environment (see Configuration files)
  • Whether the output directory is available
  • Whether object storage is configured correctly
  • Whether the MySQL connection parameters are correct
  • Whether MySQL TLS verification failed

If the task shows Partial success, review what was skipped and which steps did not finish (see Why “Partial success”?).

Why does the task show “Partial success”?

Partial success means the job finished but some items failed or were skipped by rules. Common cases:

  • Some source paths are not accessible
  • Some content was filtered by exclusion rules
  • A step in upload, encryption, or cleanup did not finish

Identify which phase failed, then re-check source paths, filters, or upload settings.

Local backup exists but nothing in object storage—what now?

Check first:

  • Whether this run used --no-upload
  • Whether the upload command actually used --apply
  • Whether [object_storage] is fully configured
  • Whether provider, bucket, prefix, endpoint, and region are correct

If the local file was created but not uploaded, run backup upload-artifact separately.

Cannot see or download files in object storage—what now?

Check first:

  • Whether the upload succeeded
  • Whether the remote key follows prefix/prj_key/filename
  • Whether bucket, prefix, and region match the current configuration
  • Whether the target file was removed by remote retention cleanup

To verify a remote artifact, run backup download-artifact, then ppk decrypt for a decrypt check.

Remote backup history keeps growing—what now?

backup run --upload does not prune remote history. Run cleanup object-storage separately if objects accumulate.

Verify before you run:

Run dry-run before the first execution, then decide whether to add --apply.

Incomplete restore or missing directories—what to check first?

Common causes include:

  • The current plan never included this directory or dataset
  • Backup source was excluded by exclusion rules
  • Wrong restore point selected
  • Unverified backup file used
  • Encrypted archive not decrypted first

For file or directory restores, recover to a staging path first, then verify content, permissions, and ownership.

Table filters not applied in multi-DB backup—what now?

First check rules in mysql_bak_request.toml:

  • Whether include_table_list is non-empty
  • Whether exclude_table_list still applies
  • Whether glob rules actually match the target tables

Note:

  • When include_table_list is non-empty, exclude_table_list is ignored
  • If include_table_list matches no tables, the command fails immediately

Backup size much larger than expected—check what first?

First check whether the backup included all of the following:

  • View Log Entry
  • Temp Directory
  • Cache directory
  • Build Product
  • Regenerable intermediate files

For complex rules, start with backup scope and exclusions and validate a few critical paths.

Could cleanup delete files you still need to restore?

Run dry-run before the first execution, then add --apply if needed. For object storage cleanup, verify bucket, prefix, and retention rules. Commands: cleanup local, cleanup object-storage.

Restore failed (private key, passphrase, or output dir)—what now?

Common causes include:

  • Private key missing or path incorrect
  • Wrong private-key passphrase (see Prerequisites · encrypted restore)
  • Corrupt or incomplete backup download
  • Decrypted output directory unavailable

Create the restore directory if missing. Decryption: ppk decrypt.

In container_exec mode, should MySQL port be inside or outside the container?

For container mysql_container_instance_a with host-mapped MySQL port 3506: in container_exec mode the client runs inside the container, so connect to 127.0.0.1:3306 inside the container—not host port 3506.