benbjohnson/litestream · error

set synchronous: %w

Error message

set synchronous: %w

What it means

populateDatabase wraps a failed "PRAGMA journal_mode = WAL" execution. The command switches the test database into WAL mode, which litestream requires in order to monitor the WAL and produce LTX files. If SQLite refuses the mode change, the tool cannot simulate a litestream-backed database and returns immediately.

Source

Thrown at cmd/litestream-test/populate.go:89

		slog.Warn("Could not remove existing database", "error", err)
	}

	db, err := sql.Open("sqlite3", c.DB)
	if err != nil {
		return fmt.Errorf("open database: %w", err)
	}
	defer db.Close()

	if _, err := db.Exec(fmt.Sprintf("PRAGMA page_size = %d", c.PageSize)); err != nil {
		return fmt.Errorf("set page size: %w", err)
	}

	if _, err := db.Exec("PRAGMA journal_mode = WAL"); err != nil {
		return fmt.Errorf("set journal mode: %w", err)
	}

	if _, err := db.Exec("PRAGMA synchronous = NORMAL"); err != nil {
		return fmt.Errorf("set synchronous: %w", err)
	}

	for i := 0; i < c.TableCount; i++ {
		tableName := fmt.Sprintf("test_table_%d", i)

		createSQL := fmt.Sprintf(`
			CREATE TABLE %s (
				id INTEGER PRIMARY KEY AUTOINCREMENT,
				data BLOB,
				text_field TEXT,
				int_field INTEGER,
				float_field REAL,
				timestamp INTEGER
			)
		`, tableName)

		if _, err := db.Exec(createSQL); err != nil {
			return fmt.Errorf("create table %s: %w", tableName, err)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Move the database to a local filesystem that supports shared memory (not NFS/SMB).
2. Close other connections holding locks on the database before populating.
3. Check that the -wal and -shm companion files are writable by the current user.
4. Inspect the wrapped SQLite error (the %w cause) for the specific SQLITE_ code.

Example fix

// before
litestream-test populate -db /mnt/nfs/data.db   // WAL unsupported on NFS
// after
litestream-test populate -db /var/tmp/data.db   // local filesystem

if fi, err := os.Stat(dbPath); err == nil {
    // reject known WAL-incompatible network mounts
    if isNetworkMount(filepath.Dir(dbPath)) {
        return fmt.Errorf("WAL mode unsupported on network filesystem: %s", filepath.Dir(dbPath))
    }
}

if _, err := db.Exec("PRAGMA journal_mode = WAL"); err != nil {
    return fmt.Errorf("set journal mode (is the fs local? is the db locked?): %w", err)
}

When it happens

Trigger: db.Exec("PRAGMA journal_mode = WAL") returns an error: the database file is on a filesystem that does not support shared memory (e.g. some network mounts), the file is locked by another connection, or the database is corrupted.

Common situations: Running the populate tool against a database on an NFS/SMB mount; a second litestream or sqlite process holding an exclusive lock; leftover -wal/-shm files with stale permissions.

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

• checkpoint: %w
• enable wal failed, mode=%q
• set page size: %w
• set journal mode: %w
• get table info: %w

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