kopia/kopia · error

error restoring

Error message

error restoring

What it means

The restore API handler wraps the result of restore.Entry — which walks the snapshot tree and writes files to the output target — with this message. Any filesystem error during restore (permissions, disk full, missing source entries) or tree-read failure is surfaced as "error restoring".

Solutions

1. Verify the restore target path exists and is writable by the server process
2. Check free disk space/quota on the target volume
3. Confirm the snapshot's blobs are not pruned (run `kopia snapshot verify`); reduce retention prunings
4. Retry the restore; check server logs for the per-file error inside restore.Entry

Example fix

// before
out := &restore.Output{} // defaults
// after
out := filesystem.NewOutput(targetDir, &filesystem.OutputOptions{
    OverwriteOverwrite: true,
    IgnorePermissionErrors: true,
})

// pre-restore checks
if err := os.MkdirAll(targetDir, 0o755); err != nil { return err }
if err := snapshot.VerifySnapshot(ctx, rep, rootID); err != nil { return err }

_, err := restore.Entry(ctx, rep, out, rootEntry, opt)
if err != nil {
    if errors.Is(err, fs.ErrPermission) {
        // retry with adjusted output options / different target
    } else if errors.Is(err, blob.ErrBlobNotFound) {
        // snapshot pruned; restore from another snapshot
    }
}

When it happens

Trigger: POST /api/v1/restore where the target directory is unwritable or full, a file listed in the snapshot no longer exists in the blob store, or the root entry cannot be read.

Common situations: Restoring to a path owned by another user; disk quota exceeded mid-restore; snapshot blobs pruned/GC'd before restore; special files (symlinks, devices) failing on the target OS.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• error creating directory
• error creating file
• error getting disk block size for target
• a snapshot time is needed to use a path as source
• cannot iterate directory

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/a9a2bb02090df96e. Report an issue: GitHub.

Appendix: source

Thrown at internal/server/api_restore.go:114

		opt := req.Options

		opt.ProgressCallback = func(_ context.Context, s restore.Stats) {
			ctrl.ReportCounters(restoreCounters(s))
		}

		cancelChan := make(chan struct{})
		opt.Cancel = cancelChan

		ctrl.OnCancel(func() {
			close(opt.Cancel)
		})

		st, err := restore.Entry(ctx, rep, out, rootEntry, opt)
		if err == nil {
			ctrl.ReportCounters(restoreCounters(st))
		}

		return errors.Wrap(err, "error restoring")
	})

	taskID := <-taskIDChan

	task, ok := rc.srv.taskManager().GetTask(taskID)
	if !ok {
		return nil, internalServerError(errors.New("task not found"))
	}

	return task, nil
}

View on GitHub (pinned to 82495e54b5)