rqlite/rqlite · error

loading snapshot %q: %w

Error message

loading snapshot %q: %w

What it means

Scan() walks the snapshot directory and calls loadSnapshot() for each entry; if any single snapshot fails to load for any reason (bad meta.json, missing data, corrupt files, CRC errors), the entire scan fails and this wrapper adds the snapshot directory name to the underlying error.

Source

Thrown at snapshot/snapshot.go:485

// multiple data files, unreadable metadata, or a mismatch between declared kind
// and observed file format), it returns an error describing the inconsistency.
// Scan does not attempt to repair or modify on-disk state.
func (c *SnapshotCatalog) Scan(dir string) (SnapshotSet, error) {
	entries, err := os.ReadDir(dir)
	if err != nil {
		return SnapshotSet{}, fmt.Errorf("reading snapshot store directory: %w", err)
	}

	var snapshots []*Snapshot
	for _, entry := range entries {
		if !entry.IsDir() || isTmpName(entry.Name()) {
			continue
		}

		snapshotPath := filepath.Join(dir, entry.Name())
		snapshot, err := c.loadSnapshot(snapshotPath, entry.Name())
		if err != nil {
			return SnapshotSet{}, fmt.Errorf("loading snapshot %q: %w", entry.Name(), err)
		}
		snapshots = append(snapshots, snapshot)
	}

	sort.Slice(snapshots, func(i, j int) bool {
		return snapshots[i].Less(snapshots[j])
	})

	return SnapshotSet{
		dir:   dir,
		items: snapshots,
	}, nil
}

func (c *SnapshotCatalog) loadSnapshot(path string, id string) (*Snapshot, error) {
	meta, err := readRaftMeta(metaPath(path))
	if err != nil {
		return nil, fmt.Errorf("reading meta.json: %w", err)

View on GitHub (pinned to 7586a4d1bd)

Solutions

  1. Inspect the wrapped inner error and the quoted snapshot name; delete or repair the offending snapshot directory and restart
  2. Restore the snapshot directory from a good backup or re-snapshot from a healthy node
  3. Check filesystem permissions and disk health (dmesg, SMART) for the data directory

Example fix

// before: node fails to start due to corrupt snapshot dir
// after: remove the bad snapshot directory
rm -rf /path/to/data/rt-snapshot-<bad-id>
# then restart rqlited
Defensive patterns

Strategy: try-catch

Validate before calling

for _, d := range snapshotDirs { if _, err := os.Stat(filepath.Join(d, "meta.json")); err != nil { /* quarantine dir */ } }

Type guard

func loadableSnapshotDir(dir string) bool { info, err := os.Stat(dir); return err == nil && info.IsDir() }

Try / catch

ss, err := catalog.Scan()
if err != nil {
    var qe *QuarantineError
    if errors.As(err, &qe) { removeBadSnapshotDir(qe.Dir); retry() }
    return err
}

Prevention

When it happens

Trigger: Calling Scan(), LatestIndexTerm(), ListAll(), Len(), or checkCRCs() when any snapshot subdirectory on disk is unreadable, incomplete, or corrupt — e.g. a partially written snapshot after a crash, or a meta.json that fails readRaftMeta().

Common situations: Disk full or process kill during snapshot write leaving a torn snapshot directory; manual copy/restore of snapshot dirs missing meta.json; permission problems on snapshot files; corrupted filesystem after power loss.

Related errors

AI-assisted analysis of rqlite/rqlite@7586a4d1bd (2026-09-03). Data as JSON: /api/errors/ce64cb24295ac85c. Report an issue: GitHub.