{"record":{"id":"02a7ecb9f82e4521","repo":"weaviate/weaviate","slug":"init-index-q-w","errorCode":null,"errorMessage":"init index %q: %w","messagePattern":"init index %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/index.go","lineNumber":538,"sourceCode":"\n\tif cfg.AsyncReplicationScheduler == nil && cfg.ReplicationFactor > 1 {\n\t\treturn nil, fmt.Errorf(\"init index %q: async replication scheduler is required when ReplicationFactor > 1\", cfg.ClassName.String())\n\t}\n\tif globalReplicationConfig == nil && cfg.ReplicationFactor > 1 {\n\t\treturn nil, fmt.Errorf(\"init index %q: global replication config is required when ReplicationFactor > 1\", cfg.ClassName.String())\n\t}\n\tindex.asyncReplicationScheduler = cfg.AsyncReplicationScheduler\n\n\tindex.closingCtx, index.closingCancel = context.WithCancel(context.Background())\n\n\tindex.initCycleCallbacks()\n\n\tif err := index.checkSingleShardMigration(); err != nil {\n\t\treturn nil, errors.Wrap(err, \"migrating sharding state from previous version\")\n\t}\n\n\tif err := os.MkdirAll(index.path(), os.ModePerm); err != nil {\n\t\treturn nil, fmt.Errorf(\"init index %q: %w\", index.ID(), err)\n\t}\n\n\t// Remove the snapshots root to clean up any bucket snapshots left behind\n\t// by operations that were interrupted (e.g. server crash). This runs once\n\t// at index creation time — not on every shard load — so it won't interfere\n\t// with a snapshot that may be in use after a tenant re-activation.\n\tif err := os.RemoveAll(index.snapshotsPath()); err != nil {\n\t\tlogger.WithField(\"action\", \"remove_orphaned_snapshots\").\n\t\t\tWithField(\"path\", index.snapshotsPath()).\n\t\t\tError(err)\n\t}\n\n\tif err := index.initAndStoreShards(ctx, class, promMetrics); err != nil {\n\t\treturn nil, err\n\t}\n\n\tindex.cycleCallbacks.compactionCycle.Start()\n\tindex.cycleCallbacks.compactionAuxCycle.Start()","sourceCodeStart":520,"sourceCodeEnd":556,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/index.go#L520-L556","documentation":"Wraps an os.MkdirAll failure while creating the index's on-disk directory during NewIndex. The index directory cannot be created, so the index (and its shards) cannot exist on this node — usually a filesystem/permission problem, not a schema problem.","triggerScenarios":"os.MkdirAll(index.path()) fails: parent directory missing and uncreatable, insufficient permissions, read-only filesystem, disk full, or the path exists as a regular file, or persistent-ancestors (PERSISTENCE_DATA_PATH) points somewhere invalid.","commonSituations":"Docker container with read-only or wrongly-mounted data volume; wrong PERSISTENCE_DATA_PATH env var; running as non-root user without write access; disk exhausted after a large import; leftover file where the index dir should be.","solutions":["Check filesystem permissions and ownership on the data directory (ls -ld; chown/chmod as needed)","Verify PERSISTENCE_DATA_PATH points to an existing writable volume","Check disk space (df -h) and free space or move the data directory","Ensure the path is not occupied by a regular file; remove/rename the offending file","If the volume is read-only, remount it read-write"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if err := os.MkdirAll(dataPath, 0o755); err != nil {\n  log.Fatalf(\"data dir not writable: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"idx, err := db.NewIndex(ctx, cfg)\nif err != nil && strings.Contains(err.Error(), \"init index\") {\n  // check PERSISTENCE_DATA_PATH mount, permissions, disk space before restart\n}","preventionTips":["Health-check that PERSISTENCE_DATA_PATH is writable at container start","Run the process as a user owning the data volume","Monitor disk usage and alert before full","Never mount the data volume read-only"],"tags":["filesystem","storage","startup"],"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"}