weaviate/weaviate · error

bucket %q: %w

Error message

bucket %q: %w

What it means

During inverted-index sorting, the sorter needs the roaring-set bucket backing the first sort property. It acquires the bucket for read; if the store has no such bucket (property has no inverted index bucket, or store not open) it returns this error wrapping lsmkv.ErrBucketNotFound. The comment notes buckets backing open cursors must be pinned for the whole sort, so this lookup failing means sorting on that property cannot proceed at all.

Source

Thrown at adapters/repos/db/sorter/inverted_sorter.go:131

	nesting int,
) ([]uint64, error) {
	if len(sort) < 1 {
		// this should never happen, the query planner should already have chosen
		// another strategy
		return nil, fmt.Errorf("no sort clause provided, expected at least one sort clause")
	}

	propNames, orders, err := extractPropNamesAndOrders(sort)
	if err != nil {
		return nil, err
	}

	// pinned for the whole sort: the bucket backs every cursor opened below,
	// and an unpinned pointer can be shut down between the lookup and the scan
	bucketName := helpers.BucketFromPropNameLSM(propNames[0])
	bucket, release := is.store.AcquireBucketForRead(bucketName)
	if bucket == nil {
		return nil, fmt.Errorf("bucket %q: %w", bucketName, lsmkv.ErrBucketNotFound)
	}
	defer release()
	if bucket.Strategy() != lsmkv.StrategyRoaringSet {
		// this should never happen, the query planner should already have chosen
		// another strategy
		return nil, fmt.Errorf("expected roaring set bucket for property %s, got %s",
			propNames[0], bucket.Strategy())
	}

	switch orders[0] {
	case "asc":
		return is.sortRoaringSetASC(ctx, bucket, limit, sort, ids, nesting)
	case "desc":
		return is.sortRoaringSetDESC(ctx, bucket, limit, sort, ids, nesting)
	default:
		return nil, fmt.Errorf("unsupported sort order %s", orders[0])
	}
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Verify the sort property exists and has filtering/sorting enabled (indexFilterable not disabled) in the collection schema.
2. Check that the shard is open and the node is not shutting down; retry the query if a shutdown/offload race is suspected.
3. If it happens after a version upgrade or reindex, rebuild the shard index so property buckets are created.
4. Inspect the wrapped lsmkv.ErrBucketNotFound in logs to confirm which bucket name is missing, and compare against the shard's actual buckets.

Example fix

// before
bucket, release := is.store.AcquireBucketForRead(bucketName)
if bucket == nil {
	return nil, fmt.Errorf("bucket %q: %w", bucketName, lsmkv.ErrBucketNotFound)
}
// after — caller-side guard
if errors.Is(err, lsmkv.ErrBucketNotFound) {
	return nil, status.NewStatusError(...)
	// or fall back to unsorted / plan a different strategy
}

bucket, _ := store.AcquireBucketForRead(helpers.BucketFromPropNameLSM(prop))
if bucket == nil { return errors.New("sort property has no inverted index bucket") }

func bucketExists(store *lsmkv.Store, prop string) bool {
	b, _ := store.AcquireBucketForRead(helpers.BucketFromPropNameLSM(prop))
	if b == nil { return false }
	defer b.Release()
	return b.Strategy() == lsmkv.StrategyRoaringSet
}

if err != nil {
	if errors.Is(err, lsmkv.ErrBucketNotFound) {
		return fallbackBruteForceSort(ctx, ids, sort) // fall back to objects-bucket sort
	}
	return err
}

When it happens

Trigger: Sort on property whose LSM bucket (helpers.BucketFromPropNameLSM) does not exist in the shard store — property name mismatch, property created before/after bucket creation, or AcquireBucketForRead returning nil because the bucket was dropped or the store is closed. Also when AcquireBucketForRead returns nil mid-shutdown between planning and execution.

Common situations: Sorting on a property that is not indexed/inverted-indexable (skipped indexing: indexFilterable/indexSearchable=false), schema migration where old shards lack the bucket, races with shard close during tenant offload, typo'd property name in GraphQL sort clause (usually caught by planner earlier).

Related errors

• process descending window: %w
• get tombstones: %w
• merge tombstones: %w
• segment file body writer is nil, cannot write inverted index
• property only supported for inverted strategy

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