{"record":{"id":"d1af4e992659e62f","repo":"rqlite/rqlite","slug":"failed-to-create-queue-bucket-w","errorCode":null,"errorMessage":"failed to create queue bucket: %w","messagePattern":"failed to create queue bucket: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cdc/fifo.go","lineNumber":76,"sourceCode":"\n\t// eventsChan is the write-side of the C channel.\n\teventsChan chan *Event\n\n\twg sync.WaitGroup\n}\n\n// NewQueue creates or opens a new persistent queue at the given file path.\nfunc NewQueue(path string) (*Queue, error) {\n\tdb, err := bbolt.Open(path, 0600, &bbolt.Options{Timeout: time.Second, NoFreelistSync: true})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to open boltdb: %w\", err)\n\t}\n\n\t// Prepare the database buckets in a single transaction.\n\tvar highestKey uint64\n\tif err := db.Update(func(tx *bbolt.Tx) error {\n\t\tif _, err := tx.CreateBucketIfNotExists(bucketName); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create queue bucket: %w\", err)\n\t\t}\n\t\tif _, err := tx.CreateBucketIfNotExists(metaBucketName); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create meta bucket: %w\", err)\n\t\t}\n\t\t// Ensure the meta bucket has a \"max_key\" entry.\n\t\tmetaBucket := tx.Bucket(metaBucketName)\n\t\tif metaBucket.Get([]byte(\"max_key\")) == nil {\n\t\t\tif err := metaBucket.Put([]byte(\"max_key\"), uint64tob(0)); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to initialize max_key: %w\", err)\n\t\t\t}\n\t\t}\n\n\t\t// Initialize state from the DB.\n\t\tvar innerErr error\n\t\thighestKey, innerErr = getHighestKey(tx)\n\t\tif innerErr != nil {\n\t\t\treturn fmt.Errorf(\"failed to get highest key: %w\", innerErr)\n\t\t}","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/rqlite/rqlite/blob/7586a4d1bdbd9a5a80021664c5a863cd850adb60/cdc/fifo.go#L58-L94","documentation":"During NewQueue's initialization transaction, tx.CreateBucketIfNotExists(bucketName) must create the FIFO data bucket. Failure here (returned inside the db.Update transaction) is wrapped and ultimately surfaces as \"failed to initialize buckets\", causing queue startup to abort and the bbolt handle to be closed.","triggerScenarios":"The bbolt write transaction cannot create the main queue bucket — practically only when the database file is corrupted (invalid meta pages / freelist) or an internal bbolt error occurs during bucket creation.","commonSituations":"Corrupted bbolt file from disk corruption or an unsafe kill (though NoFreelistSync mitigates some of this); filesystem-level bit rot; running on unreliable storage.","solutions":["Check the wrapped error for the specific bbolt cause; bucket-creation failures usually indicate file corruption.","Stop rqlited, back up the queue file, and delete it so a fresh queue is created — queued but undelivered CDC events will be lost.","Verify disk health (SMART, dmesg) if corruption recurs.","Re-run rqlited; CDC will resume capturing new changes into the fresh queue."],"exampleFix":"// before: corrupt queue file blocks startup\n$ mv ~/node/queue.db ~/node/queue.db.corrupt\n// after: rqlited recreates queue cleanly on next start\n$ rqlited -cdc-queue-path ~/node/queue.db ~/node","handlingStrategy":"fallback","validationCode":"// no pre-call validation; corruption is detected at open — recover instead\n// probe: bbolt open + read-only tx succeeds?\nif db, err := bbolt.Open(path, 0600, &bbolt.Options{Timeout: time.Second}); err == nil {\n    err = db.View(func(tx *bbolt.Tx) error { return nil })\n    db.Close()\n    // err != nil => file corrupt, replace before service start\n}","typeGuard":null,"tryCatchPattern":"q, err := cdc.NewQueue(path)\nif err != nil {\n    // fallback: archive corrupt queue and recreate (accepting event loss)\n    os.Rename(path, path+\".corrupt-\")\n    if q, err = cdc.NewQueue(path); err != nil {\n        log.Fatalf(\"cdc queue unrecoverable: %v\", err)\n    }\n    log.Printf(\"recreated corrupt CDC queue\")\n}","preventionTips":["Run rqlited on healthy storage with UPS; avoid kill -9 in operational scripts","Back up queue.db before maintenance","Alert on any \"failed to initialize buckets\" wrapper — it signals corruption","Monitor disk SMART health on nodes with CDC enabled"],"tags":["boltdb","cdc","corruption"],"backgroundTag":"boltdb-corruption","analyzedSha":"7586a4d1bdbd9a5a80021664c5a863cd850adb60","analyzedAt":"2026-09-03T07:03:02.260Z","contentChangedAt":"2026-09-03T07:03:02.260Z","schemaVersion":2},"datasetVersion":"2026-09-10T12:17:11.382Z"}