benbjohnson/litestream · error

integrity check: %w

Error message

integrity check: %w

What it means

checkIntegrity runs 'PRAGMA quick_check' or 'PRAGMA integrity_check' via db.QueryRowContext and this error wraps a failure to execute/scan that query — as opposed to the check returning a bad result. It indicates SQLite could not run the check: database open/IO errors, context cancellation, or driver-level failures.

Source

Thrown at replica.go:1355

	db, err := sql.Open("sqlite", dbPath)
	if err != nil {
		return fmt.Errorf("open database for integrity check: %w", err)
	}
	defer func() { _ = db.Close() }()

	var pragma string
	switch mode {
	case IntegrityCheckQuick:
		pragma = "quick_check"
	case IntegrityCheckFull:
		pragma = "integrity_check"
	default:
		return fmt.Errorf("unsupported integrity check mode: %d", mode)
	}

	var result string
	if err := db.QueryRowContext(ctx, "PRAGMA "+pragma).Scan(&result); err != nil {
		return fmt.Errorf("integrity check: %w", err)
	}
	if result != "ok" {
		return fmt.Errorf("integrity check failed: %s", result)
	}

	// Clean up -shm and -wal files that SQLite may create during the PRAGMA.
	_ = os.Remove(dbPath + "-shm")
	_ = os.Remove(dbPath + "-wal")

	return nil
}

// findBestV3SnapshotForTimestamp returns the best v0.3.x snapshot for the given timestamp.
// Returns nil if no suitable snapshot exists.
func (r *Replica) findBestV3SnapshotForTimestamp(ctx context.Context, client ReplicaClientV3, timestamp time.Time) (*SnapshotInfoV3, error) {
	generations, err := client.GenerationsV3(ctx)
	if err != nil {
		return nil, fmt.Errorf("list v0.3.x generations: %w", err)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the wrapped driver error for 'interrupted' (context) vs I/O messages.
2. Increase the context deadline/timeout for large restores.
3. Ensure no other process is holding db.sqlite, -wal, or -shm open during restore.
4. Re-run the restore to rule out a transient I/O error.
5. If the driver reports disk I/O errors, check hardware/filesystem health.

Example fix

// before
ctx := context.Background()
// after
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
defer cancel()

if err := restore(ctx, opt); err != nil && strings.Contains(err.Error(), "integrity check:") {
    if errors.Is(err, context.DeadlineExceeded) {
        // retry with a larger timeout
    }
}

When it happens

Trigger: Restore with IntegrityCheck enabled where QueryRowContext(ctx, "PRAGMA "+pragma).Scan(&result) errors: ctx cancelled/timed out mid-PRAGMA, unreadable/corrupt file causing driver errors, or the restored file being locked by another process.

Common situations: Very large databases with a short context deadline; another process holding the restored DB open during the check; antivirus/backup software interfering with the file; disk I/O errors.

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

• set page size: %w
• set journal mode: %w
• set synchronous: %w
• checkpoint: %w
• get table info: %w

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/398a0770c4a2b48e. Report an issue: GitHub.