pocketbase/pocketbase · error

missing or invalid backup file %q to restore

Error message

missing or invalid backup file %q to restore

What it means

Thrown by RestoreBackup when the requested backup name does not exist in the backups filesystem (local pb_data/backups or S3 when enabled). Exists(name) also swallows lookup errors, so an inaccessible S3 bucket yields the same message.

Source

Thrown at core/base_backup.go:191

		}

		// make sure that the special temp directory exists
		// note: it needs to be inside the current pb_data to avoid "cross-device link" errors
		localTempDir := filepath.Join(e.App.DataDir(), LocalTempDirName)
		if err := os.MkdirAll(localTempDir, os.ModePerm); err != nil {
			return fmt.Errorf("failed to create a temp dir: %w", err)
		}

		fsys, err := e.App.NewBackupsFilesystem()
		if err != nil {
			return err
		}
		defer fsys.Close()

		fsys.SetContext(e.Context)

		if ok, _ := fsys.Exists(name); !ok {
			return fmt.Errorf("missing or invalid backup file %q to restore", name)
		}

		extractedDataDir := filepath.Join(localTempDir, "pb_restore_"+security.PseudorandomString(8))
		defer os.RemoveAll(extractedDataDir)

		// extract the zip
		if e.App.Settings().Backups.S3.Enabled {
			br, err := fsys.GetReader(name)
			if err != nil {
				return err
			}
			defer br.Close()

			// create a temp zip file from the blob.Reader and try to extract it
			tempZip, err := os.CreateTemp(localTempDir, "pb_restore_zip")
			if err != nil {
				return err
			}

View on GitHub (pinned to 5d217ddb50)

Solutions

1. List the actual available backups first: app.Backups() (or the Admin UI backups tab) and use an exact name
2. If backups live in S3, verify Settings > Backups > S3 is enabled and credentials/bucket are correct before restoring
3. Check pb_data/backups/ contents for the expected file
4. Quote the name exactly — it is matched verbatim against the filesystem key

Example fix

// before
app.RestoreBackup(context.Background(), "backups/pb_backup_2026.zip") // wrong prefix
// after
backups, _ := app.Backups(ctx)
// pick the exact name, e.g. "pb_backup_2026.zip"
app.RestoreBackup(ctx, backups[0].Name)

fsys, err := app.NewBackupsFilesystem()
if err != nil { return err }
defer fsys.Close()
if ok, _ := fsys.Exists(name); !ok {
    return fmt.Errorf("no such backup %q - listing backups instead", name)
}

if err := app.RestoreBackup(ctx, name); err != nil {
    if strings.Contains(err.Error(), "missing or invalid backup file") {
        names, _ := app.Backups(ctx)
        // surface valid names to the operator
    }
}

When it happens

Trigger: Calling app.RestoreBackup(name) with a name that is not present: typo, file deleted from pb_data/backups, S3 backup referenced while S3 is disabled/misconfigured in settings, or name including a path prefix that does not match the stored key.

Common situations: Copy-pasting a backup filename from another environment; S3 backups listed in settings but the S3 config was changed so the local filesystem is consulted instead; passing the full path instead of the basename.

Related errors

• data.db file is missing or invalid: %w
• Uploader.Key is required
• failed to move the current pb_data content to a temp locatio
• failed to move the extracted archive content to pb_data: %w
• failed to revert the extracted dir change: %w

AI-assisted analysis of pocketbase/pocketbase@5d217ddb50 (2026-08-15). Data as JSON: /api/errors/d8dbb4ea4c987bca. Report an issue: GitHub.