benbjohnson/litestream · error

ensure wal exists: %w

Error message

ensure wal exists: %w

What it means

db.Open failed in ensureWALExists, which forces at least one frame into the WAL so shadow-WAL syncing has a starting point. Failure means the WAL could not be initialized — usually the SQLite write or checkpoint needed to seed the WAL errored.

Source

Thrown at db.go:1115

	if err := db.acquireReadLock(ctx); err != nil {
		return fmt.Errorf("acquire read lock: %w", err)
	}

	// Read page size.
	if err := db.db.QueryRowContext(ctx, `PRAGMA page_size;`).Scan(&db.pageSize); err != nil {
		return fmt.Errorf("read page size: %w", err)
	} else if db.pageSize <= 0 {
		return fmt.Errorf("invalid db page size: %d", db.pageSize)
	}

	// Ensure meta directory structure exists.
	if err := internal.MkdirAll(db.metaPath, db.dirInfo); err != nil {
		return err
	}

	// Ensure WAL has at least one frame in it.
	if err := db.ensureWALExists(ctx); err != nil {
		return fmt.Errorf("ensure wal exists: %w", err)
	}

	// Check if database is behind replica (issue #781).
	// This must happen before replica.Start() to detect restore scenarios.
	if db.Replica != nil {
		if err := db.checkDatabaseBehindReplica(ctx); err != nil {
			return fmt.Errorf("check database behind replica: %w", err)
		}
	}

	// If we have an existing replication files, ensure the headers match.
	// if err := db.verifyHeadersMatch(); err != nil {
	// 	return fmt.Errorf("cannot determine last wal position: %w", err)
	// }

	// TODO(gen): Generate diff of current LTX snapshot and save as next LTX file.

	// Start replication.

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check database file and WAL file permissions
2. Verify the database is not locked by another exclusive process
3. Inspect the wrapped SQLite error for the root cause

When it happens

Trigger: Thrown at db.go:1115 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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