weaviate/weaviate · error

determine dimensions bucket strategy: %w

Error message

determine dimensions bucket strategy: %w

What it means

openUnloadedDimensionsBucket first determines which persisted strategy the dimensions LSM bucket on disk was created with (from the prioritized strategies for dimensions buckets) before opening it read-only. This error wraps a failure of that determination, which typically means the bucket directory does not exist or its descriptor files are unreadable. It happens when calculating usage for a shard that has no dimensions bucket on disk.

Source

Thrown at adapters/repos/db/shard_usage/usage.go:153

	}
	return usageDisk, nil
}

// unloadedDimensionsBucketLocks serializes access to the same unloaded dimensions bucket.
// Concurrent usage reports (overlapping periodic collections, /debug/usage, both usage modules
// enabled) and the node-wide metrics observer may otherwise open the same bucket at once,
// which lsmkv's GlobalBucketRegistry rejects with "bucket already registered".
var unloadedDimensionsBucketLocks = entsync.NewKeyLockerContext()

// openUnloadedDimensionsBucket opens the dimensions bucket of an unloaded shard without
// loading the shard into memory. The bucket is opened with a sequential-access hint, as the
// dimension calculations scan it with cursors.
// Callers must hold the unloadedDimensionsBucketLocks lock for bucketPath until the returned
// bucket is shut down.
func openUnloadedDimensionsBucket(ctx context.Context, logger logrus.FieldLogger, path, bucketPath string) (*lsmkv.Bucket, error) {
	strategy, err := lsmkv.DetermineUnloadedBucketStrategyAmong(bucketPath, lsmkv.DimensionsBucketPrioritizedStrategies)
	if err != nil {
		return nil, fmt.Errorf("determine dimensions bucket strategy: %w", err)
	}

	return lsmkv.NewBucketCreator().NewBucket(ctx,
		bucketPath,
		path,
		logger,
		nil,
		cyclemanager.NewCallbackGroupNoop(),
		cyclemanager.NewCallbackGroupNoop(),
		lsmkv.WithStrategy(strategy),
		lsmkv.WithSequentialAccess(true),
	)
}

// CalculateUnloadedDimensionsUsage calculates dimensions and object count for an unloaded shard without loading it into memory
func CalculateUnloadedDimensionsUsage(ctx context.Context, logger logrus.FieldLogger, path, tenantName, targetVector string) (types.Dimensionality, error) {
	bucketPath := shardPathDimensionsLSM(path, tenantName)
	if err := unloadedDimensionsBucketLocks.LockWithContext(bucketPath, ctx); err != nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Verify the shard/tenant exists on this node and the dimensions directory exists under the shard path; re-create or re-sync the shard if missing.
2. Check permissions/ownership of the data directory for the Weaviate process user.
3. For a genuinely empty/new shard, skip usage calculation or initialize the shard first.
4. Inspect the wrapped inner error (os.IsNotExist vs permission vs I/O) to pick the fix.

Example fix

// before (assuming bucket always exists)
dims, err := shard_usage.CalculateUnloadedDimensionsUsage(ctx, logger, path, tenant, vec)
if err != nil { return err }
// after
if _, err := os.Stat(filepath.Join(path, tenant)); errors.Is(err, fs.ErrNotExist) {
	return types.Dimensionality{}, nil // shard not present on this node
}
dims, err := shard_usage.CalculateUnloadedDimensionsUsage(ctx, logger, path, tenant, vec)

dimsDir := filepath.Join(path, tenant, "lsm", "dimensions") // or shardPathDimensionsLSM equivalent
if _, err := os.Stat(dimsDir); errors.Is(err, fs.ErrNotExist) {
	return types.Dimensionality{}, nil // shard/dimensions bucket not present on this node
}

dims, err := shard_usage.CalculateUnloadedDimensionsUsage(ctx, logger, path, tenant, vec)
if err != nil {
	if errors.Is(err, fs.ErrNotExist) { return types.Dimensionality{}, nil }
	return fmt.Errorf("unloaded dimensions usage failed: %w", err)
}

When it happens

Trigger: Calling CalculateUnloadedDimensionsUsage / CalculateUnloadedDimensionsUsageAll for a tenant/shard whose dimensions LSM directory (shardPathDimensionsLSM path) is missing, was not yet flushed/created, or is unreadable due to permissions or I/O error.

Common situations: Querying usage for a tenant that was never materialized on this node; shard directory partially deleted; async replication lag so the shard exists logically but not on disk yet; permission problems after restoring data.

Related errors

• object bucket does not exist
• buildRecGroupExecutor: meta bucket for %q not found
• objects bucket not found
• getting objects bucket class name: %w
• evalNot: read _exists for %q: %w

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