What causes "open database for integrity check: %w" in benbjohnson/litestream?

Ensure modernc.org/sqlite is imported (blank import: _ "modernc.org/sqlite") so the 'sqlite' driver registers.

open database for integrity check: %w

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.

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)

Solutions

Ensure modernc.org/sqlite is imported (blank import: _ "modernc.org/sqlite") so the 'sqlite' driver registers.
Check sql.Drivers() at startup for the 'sqlite' driver name.
If using another driver, rebuild Litestream unmodified — it requires modernc.org/sqlite.
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"
)

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Blank-import modernc.org/sqlite in any binary embedding Litestream
Assert the 'sqlite' driver is registered at startup
Avoid mixing CGO SQLite drivers that collide on the 'sqlite' name
Pin modernc.org/sqlite in go.mod during dependency upgrades

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

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