{"record":{"id":"f44eca0e78fe26bf","repo":"weaviate/weaviate","slug":"invalid-sharding-state-virtual-shards-unavailable","errorCode":null,"errorMessage":"invalid sharding state: virtual shards unavailable","messagePattern":"invalid sharding state: virtual shards unavailable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cluster/schema/reader.go","lineNumber":109,"sourceCode":"// This check is typically called before executing read operations via\n// SchemaReader to avoid panics on partially initialized state.\nfunc checkShardingState(s *sharding.State) error {\n\tif s == nil {\n\t\treturn fmt.Errorf(\"invalid sharding state: state is nil\")\n\t}\n\n\tif s.PartitioningEnabled {\n\t\t// If we are multi-tenant, and there is no physical map (e.g. no tenants at all in the collection)\n\t\t// then just return early without error\n\t\treturn nil\n\t}\n\n\t// Non-partitioned mode: both Physical and Virtual must be (non-nil and) non-empty;\n\tif len(s.Physical) == 0 {\n\t\treturn fmt.Errorf(\"invalid sharding state: physical shards unavailable\")\n\t}\n\tif len(s.Virtual) == 0 {\n\t\treturn fmt.Errorf(\"invalid sharding state: virtual shards unavailable\")\n\t}\n\n\treturn nil\n}\n\n// Read performs a read operation `reader` on the specified class and sharding state\nfunc (rs SchemaReader) Read(class string, retryIfClassNotFound bool, reader func(*models.Class, *sharding.State) error) error {\n\tt := prometheus.NewTimer(monitoring.GetMetrics().SchemaReadsLocal.WithLabelValues(\"Read\"))\n\tdefer t.ObserveDuration()\n\n\treturn rs.retry(func(s *schema) error {\n\t\treturn s.Read(class, retryIfClassNotFound, func(class *models.Class, state *sharding.State) error {\n\t\t\tif err := checkShardingState(state); err != nil {\n\t\t\t\t// an invalid sharding state does not become valid by waiting\n\t\t\t\treturn backoff.Permanent(err)\n\t\t\t}\n\t\t\treturn reader(class, state)\n\t\t})","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/cluster/schema/reader.go#L91-L127","documentation":"checkShardingState requires non-empty Virtual shards for non-partitioned classes. An empty Virtual map means the sharding state has no virtual shard assignments, so bucketing reads to physical shards is impossible and the read is refused.","triggerScenarios":"Read operations on a non-partitioned class whose sharding.State.Virtual map is nil/empty while Physical is fine — typically from truncated or partial state persistence or a bad migration.","commonSituations":"Incomplete snapshot restores; upgrading from versions with different sharding state formats; interrupted class creation persisting Physical but not Virtual.","solutions":["Restore the class/collection from a consistent backup","Delete and recreate the class so the sharding state is rebuilt with a full virtual-shard map","Compare sharding state format against the current Weaviate version and re-import data if migrated from an incompatible version","Check schema persistence files/RAFT logs for truncation at the time of class creation"],"exampleFix":"// before\n// Virtual map empty after partial restore -> reads fail\n// after\nclient.Backup().Restore(backupID, class) // restore full state including virtual shards","handlingStrategy":"retry","validationCode":null,"typeGuard":"func shardingStateValid(s *sharding.State) bool {\n  return s != nil && (s.PartitioningEnabled || (len(s.Physical) > 0 && len(s.Virtual) > 0))\n}","tryCatchPattern":"if strings.Contains(err.Error(), \"virtual shards unavailable\") { restoreFromBackup(class) }","preventionTips":["Restore only from complete, checksum-verified backups","Use compatible Weaviate versions between backup and restore","Allow class creation to finish uninterrupted"],"tags":["sharding","schema","corruption","virtual-shards"],"backgroundTag":"invalid-sharding-state","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"}