kopia/kopia · error

unable to load snapshots

Error message

unable to load snapshots

What it means

After finding snapshot manifest IDs, tryToConvertPathToID loads the full snapshot manifests via snapshot.LoadSnapshots. If that load fails (repository read error, corruption, connectivity), the error is wrapped with 'unable to load snapshots'. This is a wrapped underlying error — the root cause is in the chained cause.

Solutions

1. Inspect the full wrapped cause (kopia prints the chain) — fix the underlying repository access error first
2. Re-run `kopia repository status` and a simple read like `kopia snapshot list` to test repository connectivity
3. Check cloud credentials and network reachability to the storage backend
4. Run `kopia repository verify-parameters` or blob-level checks if corruption is suspected; restore from a replica if available

// pre-check repository health
if err := exec.Command("kopia", "repository", "status").Run(); err != nil {
    return fmt.Errorf("repository not accessible: %w", err)
}

manifests, err := snapshot.LoadSnapshots(ctx, rep, ids)
if err != nil {
    var retryable = isNetworkOrTempError(err)
    if retryable { /* backoff and retry */ }
    return fmt.Errorf("check repo connectivity/credentials: %w", err)
}

When it happens

Trigger: Calling kopia restore where manifest IDs exist but loading them from the repository fails — repository backend unreachable (S3/Blob/network issues), manifest data corrupted, or blob storage access denied.

Common situations: Network interruption to object storage during restore; expired/revoked cloud storage credentials; corrupted manifest blobs in the repository; concurrent maintenance deleting blobs mid-read.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• error restoring
• can't save policy for
• could not get defined policy for source
• error reading directory
• error writing placeholder

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

Appendix: source

Thrown at cli/command_restore.go:508

		return "", errors.Errorf("invalid directory: '%s': %s", source, err)
	}

	if si.Path == "" {
		return "", errors.New("the source must contain a path element")
	}

	manifestIDs, err := findSnapshotsForSource(ctx, rep, si, map[string]string{})
	if err != nil {
		return "", err
	}

	if len(manifestIDs) == 0 {
		return "", errors.Errorf("no snapshots contain data for %v", source)
	}

	ms, err := snapshot.LoadSnapshots(ctx, rep, manifestIDs)
	if err != nil {
		return "", errors.Wrap(err, "unable to load snapshots")
	}

	m, relPath, ohid := findLastManifestWithPath(ctx, rep, ms, si.Path, filter)
	if m == nil {
		return "", errors.Errorf("no snapshots contain data for %v", source)
	}

	log(ctx).Infof("Restoring from\n"+
		"   Snapshot source: %v\n"+
		"   Snapshot time: %v\n"+
		"   Relative path: %v\n"+
		"   Object ID: %v", m.Source, formatTimestamp(m.StartTime.ToTime()), relPath, ohid)

	return ohid.String(), nil
}

func createSnapshotTimeFilter(timespec string) (func(*snapshot.Manifest, int, int) bool, error) {
	if timespec == "" || timespec == "latest" {

View on GitHub (pinned to 82495e54b5)