{"record":{"id":"fac9c444f5c2f9e6","repo":"benbjohnson/litestream","slug":"create-litestream-seq-table-w","errorCode":null,"errorMessage":"create _litestream_seq table: %w","messagePattern":"create _litestream_seq table: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":1086,"sourceCode":"\t\t\tdb.db.Close()\n\t\t\tdb.f.Close()\n\t\t\tdb.db, db.f = nil, nil\n\t\t}\n\t}()\n\n\t// Enable WAL and ensure it is set. New mode should be returned on success:\n\t// https://www.sqlite.org/pragma.html#pragma_journal_mode\n\tvar mode string\n\tif err := db.db.QueryRowContext(ctx, `PRAGMA journal_mode = wal;`).Scan(&mode); err != nil {\n\t\treturn err\n\t} else if mode != \"wal\" {\n\t\treturn fmt.Errorf(\"enable wal failed, mode=%q\", mode)\n\t}\n\n\t// Create a table to force writes to the WAL when empty.\n\t// There should only ever be one row with id=1.\n\tif _, err := db.db.ExecContext(ctx, `CREATE TABLE IF NOT EXISTS _litestream_seq (id INTEGER PRIMARY KEY, seq INTEGER);`); err != nil {\n\t\treturn fmt.Errorf(\"create _litestream_seq table: %w\", err)\n\t}\n\n\t// Create a lock table to force write locks during sync.\n\t// The sync write transaction always rolls back so no data should be in this table.\n\tif _, err := db.db.ExecContext(ctx, `CREATE TABLE IF NOT EXISTS _litestream_lock (id INTEGER);`); err != nil {\n\t\treturn fmt.Errorf(\"create _litestream_lock table: %w\", err)\n\t}\n\n\t// Start a long-running read transaction to prevent other transactions\n\t// from checkpointing.\n\tif err := db.acquireReadLock(ctx); err != nil {\n\t\treturn fmt.Errorf(\"acquire read lock: %w\", err)\n\t}\n\n\t// Read page size.\n\tif err := db.db.QueryRowContext(ctx, `PRAGMA page_size;`).Scan(&db.pageSize); err != nil {\n\t\treturn fmt.Errorf(\"read page size: %w\", err)\n\t} else if db.pageSize <= 0 {","sourceCodeStart":1068,"sourceCodeEnd":1104,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L1068-L1104","documentation":"Litestream wraps a failure to create the internal `_litestream_seq` bookkeeping table during DB initialization (db.init). This table forces a write into the WAL when the database is empty so that replication has a starting point. The error wraps the underlying SQLite driver error, so the real cause (disk full, permissions, corruption, connection failure) is in the wrapped message.","triggerScenarios":"Calling litestream replicate / Open on a database whose SQLite connection cannot execute the `CREATE TABLE IF NOT EXISTS _litestream_seq` statement: read-only database file or directory, disk full, corrupted schema, `database is locked` from another process holding a write lock, or a non-SQLite/invalid file at the configured path.","commonSituations":"Pointing Litestream at a database on a read-only mount or with wrong file permissions; another Litestream instance or heavy writer holding the write lock (SQLITE_BUSY); running out of disk space on the data volume; the path is not a valid SQLite database (e.g. empty or encrypted file).","solutions":["Check file system permissions and free disk space on the database volume; ensure the file is writable by the Litestream user.","Ensure no other process holds the SQLite write lock (stop other writers or other litestream instances) and consider a busy_timeout.","Verify the file is a valid SQLite database with `sqlite3 path 'PRAGMA integrity_check;'`.","Re-open with a writable connection string/driver; if using litestream-yumrik/CGO-less driver, ensure the DSN does not set mode=ro."],"exampleFix":"// before\nlitestream replicate -config /etc/litestream.yml   # db on read-only NFS mount -> fails\n// after\nmount -o rw ... /var/lib/app   # or chown litestream:litestream /var/lib/app/app.db","handlingStrategy":"try-catch","validationCode":"// before opening with litestream\nconst os = require('os'); const fs = require('fs');\nconst st = fs.statSync(dbPath);\nif (!fs.accessSync(dbPath, fs.constants.W_OK)) throw new Error('db not writable: ' + dbPath);\nif (st.size > 0 && fs.readFileSync(dbPath).slice(0,15).toString() !== 'SQLite format 3') throw new Error('not a sqlite db');","typeGuard":"function isWritableSqliteFile(p) {\n  try { const fd = fs.openSync(p, 'r+'); const buf = Buffer.alloc(16); fs.readSync(fd, buf, 0, 16, 0); fs.closeSync(fd); return buf.toString('latin1').startsWith('SQLite format 3'); }\n  catch { return false; }\n}","tryCatchPattern":"try {\n  await db.Open(ctx);\n} catch (err) {\n  if (String(err.message).includes('create _litestream_seq table')) {\n    // inspect err.cause: EACCES/ENOSPC/SQLITE_BUSY\n    logger.error('litestream init failed on seq table', { cause: err.cause });\n    // check disk space & permissions, then retry with backoff\n  }\n}","preventionTips":["Ensure the Litestream user owns write access to the database file and directory.","Monitor disk space on the data volume.","Run only one Litestream process per database.","Validate the file is a real SQLite DB before pointing Litestream at it."],"tags":["sqlite","database","init","sql"],"backgroundTag":"database-write-failed","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}