{"record":{"id":"bb4d7cf19cd27e4c","repo":"weaviate/weaviate","slug":"migrating-sharding-state-from-previous-version","errorCode":null,"errorMessage":"migrating sharding state from previous version","messagePattern":"migrating sharding state from previous version","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/index.go","lineNumber":534,"sourceCode":"\tindex.replicator, err = replica.NewReplicator(cfg.ClassName.String(), router, nodeResolver, sg.NodeName(), getDeletionStrategy, replicaClient, promMetrics, logger)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"create replicator for index %q: %w\", index.ID(), err)\n\t}\n\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","sourceCodeStart":516,"sourceCodeEnd":552,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/index.go#L516-L552","documentation":"NewIndex detected a persisted sharding state file written by an older Weaviate version (pre-raft/no explicit physical state) and failed while migrating it forward. The collection's on-disk metadata cannot be upgraded in place, so index creation aborts rather than risking placement inconsistency.","triggerScenarios":"Thrown at adapters/repos/db/index.go:534 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Follow the documented upgrade path: upgrade through the required intermediate Weaviate version before the current one","Backup the data directory before retrying, in case the migration partially ran","Inspect the wrapped cause; if the sharding state file is corrupt, restore from backup"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}