weaviate/weaviate · error

invalid sharding state: virtual shards unavailable

Error message

invalid sharding state: virtual shards unavailable

What it means

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.

Source

Thrown at cluster/schema/reader.go:109

// This check is typically called before executing read operations via
// SchemaReader to avoid panics on partially initialized state.
func checkShardingState(s *sharding.State) error {
	if s == nil {
		return fmt.Errorf("invalid sharding state: state is nil")
	}

	if s.PartitioningEnabled {
		// If we are multi-tenant, and there is no physical map (e.g. no tenants at all in the collection)
		// then just return early without error
		return nil
	}

	// Non-partitioned mode: both Physical and Virtual must be (non-nil and) non-empty;
	if len(s.Physical) == 0 {
		return fmt.Errorf("invalid sharding state: physical shards unavailable")
	}
	if len(s.Virtual) == 0 {
		return fmt.Errorf("invalid sharding state: virtual shards unavailable")
	}

	return nil
}

// Read performs a read operation `reader` on the specified class and sharding state
func (rs SchemaReader) Read(class string, retryIfClassNotFound bool, reader func(*models.Class, *sharding.State) error) error {
	t := prometheus.NewTimer(monitoring.GetMetrics().SchemaReadsLocal.WithLabelValues("Read"))
	defer t.ObserveDuration()

	return rs.retry(func(s *schema) error {
		return s.Read(class, retryIfClassNotFound, func(class *models.Class, state *sharding.State) error {
			if err := checkShardingState(state); err != nil {
				// an invalid sharding state does not become valid by waiting
				return backoff.Permanent(err)
			}
			return reader(class, state)
		})

View on GitHub (pinned to 75aa4b6d11)

Solutions

  1. Restore the class/collection from a consistent backup
  2. Delete and recreate the class so the sharding state is rebuilt with a full virtual-shard map
  3. Compare sharding state format against the current Weaviate version and re-import data if migrated from an incompatible version
  4. Check schema persistence files/RAFT logs for truncation at the time of class creation

Example fix

// before
// Virtual map empty after partial restore -> reads fail
// after
client.Backup().Restore(backupID, class) // restore full state including virtual shards
Defensive patterns

Strategy: retry

Type guard

func shardingStateValid(s *sharding.State) bool {
  return s != nil && (s.PartitioningEnabled || (len(s.Physical) > 0 && len(s.Virtual) > 0))
}

Try / catch

if strings.Contains(err.Error(), "virtual shards unavailable") { restoreFromBackup(class) }

Prevention

When it happens

Trigger: 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.

Common situations: Incomplete snapshot restores; upgrading from versions with different sharding state formats; interrupted class creation persisting Physical but not Virtual.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/f44eca0e78fe26bf. Report an issue: GitHub.