What causes "scanning snapshots for CRC check: %w" in rqlite/rqlite?

Inspect the wrapped error and check the snapshot directories under the data dir are readable

scanning snapshots for CRC check: %w

Error message

scanning snapshots for CRC check: %w

What it means

checkCRCs verifies the CRC32 of every data file in every snapshot directory. This error is returned when the catalog's Scan(s.dir) fails before any CRC checking starts, so snapshot integrity could not even be enumerated.

Source

Thrown at snapshot/store.go:887

	}
	for _, e := range entries {
		if e.IsDir() && isTmpName(e.Name()) {
			tmpPath := filepath.Join(s.dir, e.Name())
			s.logger.Printf("removing leftover temporary directory %s", tmpPath)
			if err := os.RemoveAll(tmpPath); err != nil {
				return fmt.Errorf("removing temporary directory %s: %w", tmpPath, err)
			}
		}
	}
	return nil
}

// checkCRCs verifies the CRC32 of every data file in every snapshot directory.
func (s *Store) checkCRCs() error {
	startT := time.Now()
	snapshots, err := s.catalog.Scan(s.dir)
	if err != nil {
		return fmt.Errorf("scanning snapshots for CRC check: %w", err)
	}
	if len(snapshots.items) == 0 {
		return nil
	}

	checker := NewCRCChecker()
	for _, snap := range snapshots.items {
		if snap.dbFile != nil {
			checker.Add(snap.dbFile)
		}
		for _, wf := range snap.walFiles {
			checker.Add(wf)
		}
	}

	if err := <-checker.Check(); err != nil {
		return err
	}

View on GitHub (pinned to 7586a4d1bd)

Solutions

Inspect the wrapped error and check the snapshot directories under the data dir are readable
Restore from backup if snapshot metadata is corrupted
Fix permissions/ownership on the data and snapshot directories
Run on a healthy disk; check dmesg for I/O errors

Example fix

// before: CRC check fails to scan snapshots
sudo chown -R rqlite:rqlite /var/lib/rqlite
// after: verification proceeds
rqlite status  # verify passes

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure snapshot subdirs are readable before verification
entries, err := os.ReadDir(snapshotRoot)
if err != nil { return err }
for _, e := range entries {
    if !e.IsDir() { continue }
    if _, err := os.ReadDir(filepath.Join(snapshotRoot, e.Name())); err != nil {
        return fmt.Errorf("snapshot dir %s unreadable: %w", e.Name(), err)
    }
}

Try / catch

// Go
if err := verifier.CheckCRCs(); err != nil {
    if strings.Contains(err.Error(), "scanning snapshots") {
        logger.Printf("snapshot store unreadable, restoring from backup: %v", err)
        // fall back to restoring a known-good backup
    }
    return err
}

Prevention

Never edit or delete files inside the snapshot store manually
Take regular backups so a corrupted store can be restored
Monitor disk health (SMART) to catch I/O errors early
Keep consistent ownership/permissions across upgrades and user changes

When it happens

Trigger: Verify() or an anonymous caller invokes checkCRCs while catalog.Scan fails, e.g. unreadable/missing snapshot directories or malformed catalog state on disk.

Common situations: Manual deletion or modification of files inside the rqlite data directory; disk errors; permission problems after user change; corrupted snapshot store after power loss.

Related errors

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