{"record":{"id":"bfdc51ee377a4650","repo":"benbjohnson/litestream","slug":"ensure-wal-exists-w","errorCode":null,"errorMessage":"ensure wal exists: %w","messagePattern":"ensure wal exists: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":1115,"sourceCode":"\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 {\n\t\treturn fmt.Errorf(\"invalid db page size: %d\", db.pageSize)\n\t}\n\n\t// Ensure meta directory structure exists.\n\tif err := internal.MkdirAll(db.metaPath, db.dirInfo); err != nil {\n\t\treturn err\n\t}\n\n\t// Ensure WAL has at least one frame in it.\n\tif err := db.ensureWALExists(ctx); err != nil {\n\t\treturn fmt.Errorf(\"ensure wal exists: %w\", err)\n\t}\n\n\t// Check if database is behind replica (issue #781).\n\t// This must happen before replica.Start() to detect restore scenarios.\n\tif db.Replica != nil {\n\t\tif err := db.checkDatabaseBehindReplica(ctx); err != nil {\n\t\t\treturn fmt.Errorf(\"check database behind replica: %w\", err)\n\t\t}\n\t}\n\n\t// If we have an existing replication files, ensure the headers match.\n\t// if err := db.verifyHeadersMatch(); err != nil {\n\t// \treturn fmt.Errorf(\"cannot determine last wal position: %w\", err)\n\t// }\n\n\t// TODO(gen): Generate diff of current LTX snapshot and save as next LTX file.\n\n\t// Start replication.","sourceCodeStart":1097,"sourceCodeEnd":1133,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L1097-L1133","documentation":"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.","triggerScenarios":"Thrown at db.go:1115 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Check database file and WAL file permissions","Verify the database is not locked by another exclusive process","Inspect the wrapped SQLite error for the root cause"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}