{"record":{"id":"4442efc4935c7b66","repo":"weaviate/weaviate","slug":"shard-q-remove-computed-usage-file-for-unloaded","errorCode":null,"errorMessage":"shard %q: remove computed usage file for unloaded shard: %w","messagePattern":"shard %q: remove computed usage file for unloaded shard: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/shard_init.go","lineNumber":53,"sourceCode":"\t\"github.com/weaviate/weaviate/entities/storagestate\"\n\t\"github.com/weaviate/weaviate/usecases/monitoring\"\n)\n\nfunc NewShard(ctx context.Context, promMetrics *monitoring.PrometheusMetrics,\n\tshardName string, index *Index, class *models.Class, jobQueueCh chan job,\n\tscheduler *queue.Scheduler, indexCheckpoints *indexcheckpoint.Checkpoints,\n\treindexer ShardReindexerV3, lazyLoadSegments bool, bitmapBufPool roaringset.BitmapBufPool,\n\tregistration monitoring.ShardRegistration,\n) (_ *Shard, err error) {\n\tstart := time.Now()\n\tindex.logger.WithFields(logrus.Fields{\n\t\t\"action\": \"init_shard\",\n\t\t\"shard\":  shardName,\n\t\t\"index\":  index.ID(),\n\t}).Debugf(\"initializing shard %q\", shardName)\n\n\tif err := shardusage.RemoveComputedUsageDataForUnloadedShard(index.path(), shardName); err != nil {\n\t\treturn nil, fmt.Errorf(\"shard %q: remove computed usage file for unloaded shard: %w\", shardName, err)\n\t}\n\n\tif err := newPropertyDeleteIndexHelper().ensureBucketsAreRemovedForNonExistentPropertyIndexes(index.path(), shardName, class); err != nil {\n\t\treturn nil, fmt.Errorf(\"shard %q: remove nonexistent property index buckets: %w\", shardName, err)\n\t}\n\n\tif err := newVectorDropIndexHelper().ensureFilesAreRemovedForDroppedVectorIndexes(index.path(), shardName, class); err != nil {\n\t\treturn nil, fmt.Errorf(\"shard %q: remove dropped vector index files: %w\", shardName, err)\n\t}\n\n\tmetrics, err := NewMetrics(index.logger, promMetrics, string(index.Config.ClassName), shardName)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"init shard %q metrics: %w\", shardName, err)\n\t}\n\tif index.Config.LazySegmentsDisabled {\n\t\tlazyLoadSegments = false // disabled globally\n\t}\n","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/shard_init.go#L35-L71","documentation":"Wraps an error from shardusage.RemoveComputedUsageDataForUnloadedShard during shard initialization. Before a shard is opened, Weaviate deletes any stale computed-usage file for that (not yet loaded) shard; if removal fails, NewShard aborts so the shard never comes up in an inconsistent state. The wrapped error names the filesystem-level cause.","triggerScenarios":"Calling NewShard (shard creation/open, including during initShard and replica snapshot creation) where deleting the computed usage file under the shard's directory fails — e.g. filesystem permission error, read-only mount, or the path being an unremovable directory.","commonSituations":"Container/VM volume mounted read-only; wrong ownership or permissions on /var/lib/weaviate after migration or restore from backup; disk full (rare for unlink) or immutable files; running as a non-root user against root-owned data after a docker permission change.","solutions":["Inspect the wrapped error to identify the filesystem cause (permission denied, read-only fs, etc.).","Fix permissions/ownership on the Weaviate data directory (chown to the user running the weaviate process).","Ensure the volume is mounted read-write and the filesystem is not full or out of inodes.","Check for immutable attributes on the usage file (chattr -i) or locks from other processes.","If a specific file is unremovable, manually delete the computed usage file for that shard while Weaviate is stopped, then restart."],"exampleFix":"// before: data dir owned by root while weaviate runs as user 999\n// ls -l /var/lib/weaviate -> root:root\n// after\ndocker exec -u root weaviate chown -R 999:999 /var/lib/weaviate","handlingStrategy":"validation","validationCode":"// pre-flight check before starting/upgrading weaviate\ndir := \"/var/lib/weaviate\"\ninfo, err := os.Stat(dir)\nif err != nil { panic(err) }\nif info.Mode().Perm()&0200 == 0 {\n    panic(\"weaviate data dir is not writable\")\n}\nprobe := filepath.Join(dir, \".write-test\")\nif err := os.WriteFile(probe, []byte(\"x\"), 0o644); err != nil {\n    panic(fmt.Sprintf(\"data dir not writable: %v\", err))\n}\nos.Remove(probe)","typeGuard":null,"tryCatchPattern":"// shard init errors are fatal at startup; guard the readiness check\nif err := client.Readiness().Do(ctx); err != nil {\n    if strings.Contains(err.Error(), \"remove computed usage file for unloaded shard\") {\n        // stop, fix filesystem permissions/ownership, restart\n        os.Exit(1)\n    }\n}","preventionTips":["Run the weaviate process as the owner of its data directory (consistent UID across deploys).","Mount data volumes read-write; never run with read-only rootfs over the data path.","Monitor disk space and inode usage.","After restoring from backup, chown the data directory to the weaviate user before starting.","Avoid immutable/locked attributes on files under the data path."],"tags":["filesystem","shard-init","permissions"],"backgroundTag":"filesystem-permission-denied","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"}