{"record":{"id":"d8dbb4ea4c987bca","repo":"pocketbase/pocketbase","slug":"missing-or-invalid-backup-file-q-to-restore","errorCode":null,"errorMessage":"missing or invalid backup file %q to restore","messagePattern":"missing or invalid backup file %q to restore","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/base_backup.go","lineNumber":191,"sourceCode":"\t\t}\n\n\t\t// make sure that the special temp directory exists\n\t\t// note: it needs to be inside the current pb_data to avoid \"cross-device link\" errors\n\t\tlocalTempDir := filepath.Join(e.App.DataDir(), LocalTempDirName)\n\t\tif err := os.MkdirAll(localTempDir, os.ModePerm); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create a temp dir: %w\", err)\n\t\t}\n\n\t\tfsys, err := e.App.NewBackupsFilesystem()\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tdefer fsys.Close()\n\n\t\tfsys.SetContext(e.Context)\n\n\t\tif ok, _ := fsys.Exists(name); !ok {\n\t\t\treturn fmt.Errorf(\"missing or invalid backup file %q to restore\", name)\n\t\t}\n\n\t\textractedDataDir := filepath.Join(localTempDir, \"pb_restore_\"+security.PseudorandomString(8))\n\t\tdefer os.RemoveAll(extractedDataDir)\n\n\t\t// extract the zip\n\t\tif e.App.Settings().Backups.S3.Enabled {\n\t\t\tbr, err := fsys.GetReader(name)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tdefer br.Close()\n\n\t\t\t// create a temp zip file from the blob.Reader and try to extract it\n\t\t\ttempZip, err := os.CreateTemp(localTempDir, \"pb_restore_zip\")\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/pocketbase/pocketbase/blob/5d217ddb50cb144d80a5d0b0bdf11b52b2c3e457/core/base_backup.go#L173-L209","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["List the actual available backups first: app.Backups() (or the Admin UI backups tab) and use an exact name","If backups live in S3, verify Settings > Backups > S3 is enabled and credentials/bucket are correct before restoring","Check pb_data/backups/ contents for the expected file","Quote the name exactly — it is matched verbatim against the filesystem key"],"exampleFix":"// before\napp.RestoreBackup(context.Background(), \"backups/pb_backup_2026.zip\") // wrong prefix\n// after\nbackups, _ := app.Backups(ctx)\n// pick the exact name, e.g. \"pb_backup_2026.zip\"\napp.RestoreBackup(ctx, backups[0].Name)","handlingStrategy":"validation","validationCode":"fsys, err := app.NewBackupsFilesystem()\nif err != nil { return err }\ndefer fsys.Close()\nif ok, _ := fsys.Exists(name); !ok {\n    return fmt.Errorf(\"no such backup %q - listing backups instead\", name)\n}","typeGuard":null,"tryCatchPattern":"if err := app.RestoreBackup(ctx, name); err != nil {\n    if strings.Contains(err.Error(), \"missing or invalid backup file\") {\n        names, _ := app.Backups(ctx)\n        // surface valid names to the operator\n    }\n}","preventionTips":["Always enumerate app.Backups() and pick from real names","Keep S3 settings consistent with where backups actually live","Automate name selection instead of typing it"],"tags":["backup","restore","s3","validation"],"backgroundTag":null,"analyzedSha":"5d217ddb50cb144d80a5d0b0bdf11b52b2c3e457","analyzedAt":"2026-08-15T10:06:33.165Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}