{"record":{"id":"bf06b38f6e6968f3","repo":"weaviate/weaviate","slug":"unexpected-error-loading-bucket-q-at-path-q-v","errorCode":null,"errorMessage":"unexpected error loading bucket %q at path %q: %v","messagePattern":"unexpected error loading bucket %q at path %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/lsmkv/store.go","lineNumber":203,"sourceCode":"//\tctx := context.Background()\n//\terr := store.CreateOrLoadBucket(ctx, \"my_bucket_name\", WithStrategy(StrategyReplace))\n//\tif err != nil { /* handle error */ }\n//\n//\t// you can now access the bucket using store.Bucket()\n//\tb := store.Bucket(\"my_bucket_name\")\nfunc (s *Store) CreateOrLoadBucket(ctx context.Context, bucketName string,\n\topts ...BucketOption,\n) (err error) {\n\tdefer func() {\n\t\tp := recover()\n\t\tif p == nil {\n\t\t\t// happy path\n\t\t\treturn\n\t\t}\n\n\t\tentsentry.Recover(p)\n\n\t\terr = fmt.Errorf(\"unexpected error loading bucket %q at path %q: %v\",\n\t\t\tbucketName, s.rootDir, p)\n\t\t// logger is already annotated to identify the store (e.g. collection +\n\t\t// shard), we only need to annotate it with the exact path of this\n\t\t// bucket.\n\t\ts.logger.\n\t\t\tWithFields(logrus.Fields{\n\t\t\t\t\"action\":   \"lsm_create_or_load_bucket\",\n\t\t\t\t\"root_dir\": s.rootDir,\n\t\t\t\t\"dir\":      s.dir,\n\t\t\t\t\"bucket\":   bucketName,\n\t\t\t}).\n\t\t\tWithError(err).Errorf(\"unexpected error loading shard\")\n\t\tenterrors.PrintStack(s.logger)\n\t}()\n\n\tif s.loadLimiter != nil {\n\t\tif err := s.loadLimiter.Acquire(ctx); err != nil {\n\t\t\treturn errors.Wrapf(err, \"acquire load limiter for bucket %q\", bucketName)","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/lsmkv/store.go#L185-L221","documentation":"This error wraps a recovered panic from CreateOrLoadBucket in the lsmkv Store. When creating or loading a bucket panics (e.g. corrupted bucket files on disk), the deferred recover converts it into this descriptive error, logs it with store/bucket path annotations, and returns it instead of crashing the process.","triggerScenarios":"A panic occurs inside s.bcreator.NewBucket while loading or creating a bucket directory under the store's rootDir — typically corrupted/torn LSM files, unrecoverable disk state, or a nil dependency during bucket init.","commonSituations":"Weaviate startup after a crash or OOM kill leaves a shard's LSM directory partially written; disk corruption; manual edits/moving of shard files under the data directory; opening a data dir written by an incompatible version.","solutions":["Inspect the logged stack trace (enterrors.PrintStack) to find the panic origin inside NewBucket","Back up the shard directory, then remove or repair the corrupt bucket directory at the logged path and let Weaviate rebuild from other sources (backups, replication)","Check disk health/filesystem errors with dmesg/SMART and free space","Verify the data directory was not written by an incompatible Weaviate version"],"exampleFix":"// before (panic propagates or is lost)\nerr := store.CreateOrLoadBucket(ctx, \"objects\", WithStrategy(StrategyReplace))\n// after (recover is internal; caller should still guard against corrupt data by validating shard dir before open)\nif _, err := os.Stat(shardDir); err != nil { /* restore from backup before opening store */ }\nerr := store.CreateOrLoadBucket(ctx, \"objects\", WithStrategy(StrategyReplace))","handlingStrategy":"try-catch","validationCode":"// validate shard dir exists and is readable before opening the store\nif info, err := os.Stat(dir); err != nil || !info.IsDir() {\n    return fmt.Errorf(\"shard dir %q missing or not a directory: %w\", dir, err)\n}","typeGuard":"func isBucketLoadPanic(err error) bool { return err != nil && strings.HasPrefix(err.Error(), \"unexpected error loading bucket\") }","tryCatchPattern":"if err := store.CreateOrLoadBucket(ctx, name, opts...); err != nil {\n    if isBucketLoadPanic(err) { logger.Errorf(\"bucket %q corrupt, restore from backup: %v\", name, err) }\n    return err\n}","preventionTips":["Keep data dirs under healthy, monitored disks; watch dmesg for I/O errors","Never manually modify files inside shard directories","Restore from backups/replication rather than reusing suspect shard dirs after a crash","Check free disk space before node startup"],"tags":["lsmkv","panic-recovery","corruption","storage"],"backgroundTag":"lsm-bucket-load-panic","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}