weaviate/weaviate · error

unexpected error loading bucket %q at path %q: %v

Error message

unexpected error loading bucket %q at path %q: %v

What it means

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.

Source

Thrown at adapters/repos/db/lsmkv/store.go:203

//	ctx := context.Background()
//	err := store.CreateOrLoadBucket(ctx, "my_bucket_name", WithStrategy(StrategyReplace))
//	if err != nil { /* handle error */ }
//
//	// you can now access the bucket using store.Bucket()
//	b := store.Bucket("my_bucket_name")
func (s *Store) CreateOrLoadBucket(ctx context.Context, bucketName string,
	opts ...BucketOption,
) (err error) {
	defer func() {
		p := recover()
		if p == nil {
			// happy path
			return
		}

		entsentry.Recover(p)

		err = fmt.Errorf("unexpected error loading bucket %q at path %q: %v",
			bucketName, s.rootDir, p)
		// logger is already annotated to identify the store (e.g. collection +
		// shard), we only need to annotate it with the exact path of this
		// bucket.
		s.logger.
			WithFields(logrus.Fields{
				"action":   "lsm_create_or_load_bucket",
				"root_dir": s.rootDir,
				"dir":      s.dir,
				"bucket":   bucketName,
			}).
			WithError(err).Errorf("unexpected error loading shard")
		enterrors.PrintStack(s.logger)
	}()

	if s.loadLimiter != nil {
		if err := s.loadLimiter.Acquire(ctx); err != nil {
			return errors.Wrapf(err, "acquire load limiter for bucket %q", bucketName)

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Inspect the logged stack trace (enterrors.PrintStack) to find the panic origin inside NewBucket
2. 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)
3. Check disk health/filesystem errors with dmesg/SMART and free space
4. Verify the data directory was not written by an incompatible Weaviate version

Example fix

// before (panic propagates or is lost)
err := store.CreateOrLoadBucket(ctx, "objects", WithStrategy(StrategyReplace))
// after (recover is internal; caller should still guard against corrupt data by validating shard dir before open)
if _, err := os.Stat(shardDir); err != nil { /* restore from backup before opening store */ }
err := store.CreateOrLoadBucket(ctx, "objects", WithStrategy(StrategyReplace))

// validate shard dir exists and is readable before opening the store
if info, err := os.Stat(dir); err != nil || !info.IsDir() {
    return fmt.Errorf("shard dir %q missing or not a directory: %w", dir, err)
}

func isBucketLoadPanic(err error) bool { return err != nil && strings.HasPrefix(err.Error(), "unexpected error loading bucket") }

if err := store.CreateOrLoadBucket(ctx, name, opts...); err != nil {
    if isBucketLoadPanic(err) { logger.Errorf("bucket %q corrupt, restore from backup: %v", name, err) }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unexpected error loading segment %q: %v
• objects bucket not found
• getting objects bucket class name: %w
• active tombstones: %w
• read tombstones: %w

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/bf06b38f6e6968f3. Report an issue: GitHub.