benbjohnson/litestream · error

open database for integrity check

Error message

open database for integrity check: %w

What it means

checkIntegrity opens the restored database with database/sql using the 'sqlite' driver (modernc.org/sqlite) to run a PRAGMA check. This error wraps a failure at sql.Open, i.e. the driver could not be used to open the file. Since Open is lazy, this usually surfaces as driver registration rather than file problems.

Solutions

1. Ensure modernc.org/sqlite is imported (blank import: _ "modernc.org/sqlite") so the 'sqlite' driver registers.
2. Check sql.Drivers() at startup for the 'sqlite' driver name.
3. If using another driver, rebuild Litestream unmodified — it requires modernc.org/sqlite.
4. Verify the module's go.mod still includes modernc.org/sqlite after vendoring/dependency updates.

Example fix

// before
import (
    "database/sql"
)
// after
import (
    "database/sql"
    _ "modernc.org/sqlite"
)

import (
    "database/sql"
    _ "modernc.org/sqlite"
)
func sqliteDriverReady() bool {
    for _, d := range sql.Drivers() {
        if d == "sqlite" { return true }
    }
    return false
}

if err := replica.Restore(ctx, opt); err != nil && strings.Contains(err.Error(), "open database for integrity check") {
    // fix driver import and retry
}

When it happens

Trigger: Restore/RestoreV3 with IntegrityCheck set (or tests TestCheckIntegrity_*) where sql.Open("sqlite", dbPath) returns an error — most commonly because the modernc.org/sqlite driver was never registered (blank import missing) or the driver name was changed.

Common situations: Embedding Litestream as a library and importing a different SQLite driver; a build dropping the modernc dependency; custom builds using CGO sqlite drivers that register under the name 'sqlite' twice or not at all.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• driver does not implement FileControl
• FileControlPersistWAL
• integrity check failed
• integrity check
• open database

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

Appendix: source

Thrown at replica.go:1339

	db, err := sql.Open("sqlite", dbPath)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	_, err = db.Exec("PRAGMA wal_checkpoint(TRUNCATE)")
	return err
}

// checkIntegrity runs a SQLite integrity check on the database at dbPath.
func checkIntegrity(ctx context.Context, dbPath string, mode IntegrityCheckMode) error {
	if mode == IntegrityCheckNone {
		return nil
	}

	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" {

View on GitHub (pinned to 4ed7a308f6)