{"record":{"id":"0b0c90b8f5f1a5bb","repo":"weaviate/weaviate","slug":"determine-dimensions-bucket-strategy-w-0b0c90","errorCode":null,"errorMessage":"determine dimensions bucket strategy: %w","messagePattern":"determine dimensions bucket strategy: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/shard_usage/usage.go","lineNumber":153,"sourceCode":"\t}\n\treturn usageDisk, nil\n}\n\n// unloadedDimensionsBucketLocks serializes access to the same unloaded dimensions bucket.\n// Concurrent usage reports (overlapping periodic collections, /debug/usage, both usage modules\n// enabled) and the node-wide metrics observer may otherwise open the same bucket at once,\n// which lsmkv's GlobalBucketRegistry rejects with \"bucket already registered\".\nvar unloadedDimensionsBucketLocks = entsync.NewKeyLockerContext()\n\n// openUnloadedDimensionsBucket opens the dimensions bucket of an unloaded shard without\n// loading the shard into memory. The bucket is opened with a sequential-access hint, as the\n// dimension calculations scan it with cursors.\n// Callers must hold the unloadedDimensionsBucketLocks lock for bucketPath until the returned\n// bucket is shut down.\nfunc openUnloadedDimensionsBucket(ctx context.Context, logger logrus.FieldLogger, path, bucketPath string) (*lsmkv.Bucket, error) {\n\tstrategy, err := lsmkv.DetermineUnloadedBucketStrategyAmong(bucketPath, lsmkv.DimensionsBucketPrioritizedStrategies)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"determine dimensions bucket strategy: %w\", err)\n\t}\n\n\treturn lsmkv.NewBucketCreator().NewBucket(ctx,\n\t\tbucketPath,\n\t\tpath,\n\t\tlogger,\n\t\tnil,\n\t\tcyclemanager.NewCallbackGroupNoop(),\n\t\tcyclemanager.NewCallbackGroupNoop(),\n\t\tlsmkv.WithStrategy(strategy),\n\t\tlsmkv.WithSequentialAccess(true),\n\t)\n}\n\n// CalculateUnloadedDimensionsUsage calculates dimensions and object count for an unloaded shard without loading it into memory\nfunc CalculateUnloadedDimensionsUsage(ctx context.Context, logger logrus.FieldLogger, path, tenantName, targetVector string) (types.Dimensionality, error) {\n\tbucketPath := shardPathDimensionsLSM(path, tenantName)\n\tif err := unloadedDimensionsBucketLocks.LockWithContext(bucketPath, ctx); err != nil {","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/shard_usage/usage.go#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Check permissions/ownership of the data directory for the Weaviate process user.","For a genuinely empty/new shard, skip usage calculation or initialize the shard first.","Inspect the wrapped inner error (os.IsNotExist vs permission vs I/O) to pick the fix."],"exampleFix":"// before (assuming bucket always exists)\ndims, err := shard_usage.CalculateUnloadedDimensionsUsage(ctx, logger, path, tenant, vec)\nif err != nil { return err }\n// after\nif _, err := os.Stat(filepath.Join(path, tenant)); errors.Is(err, fs.ErrNotExist) {\n\treturn types.Dimensionality{}, nil // shard not present on this node\n}\ndims, err := shard_usage.CalculateUnloadedDimensionsUsage(ctx, logger, path, tenant, vec)","handlingStrategy":"validation","validationCode":"dimsDir := filepath.Join(path, tenant, \"lsm\", \"dimensions\") // or shardPathDimensionsLSM equivalent\nif _, err := os.Stat(dimsDir); errors.Is(err, fs.ErrNotExist) {\n\treturn types.Dimensionality{}, nil // shard/dimensions bucket not present on this node\n}","typeGuard":null,"tryCatchPattern":"dims, err := shard_usage.CalculateUnloadedDimensionsUsage(ctx, logger, path, tenant, vec)\nif err != nil {\n\tif errors.Is(err, fs.ErrNotExist) { return types.Dimensionality{}, nil }\n\treturn fmt.Errorf(\"unloaded dimensions usage failed: %w\", err)\n}","preventionTips":["Check that the tenant/shard is actually materialized on this node before computing usage.","Keep data-dir permissions consistent (same UID as the Weaviate process).","Inspect the wrapped cause (not-exist vs permission vs I/O) before retrying."],"tags":["lsmkv","storage","bucket","weaviate"],"backgroundTag":"bucket-not-found","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"}