weaviate/weaviate · error

error while trying to find shard: %s in collection: %s

Error message

error while trying to find shard: %s in collection: %s

What it means

targetShards walks the class's shards (physical or partitioned) looking for the requested shardName; if none matches, it returns this error. It means the shard simply is not part of the collection's shard set on this router, so no routing plan can be built.

Source

Thrown at cluster/router/router.go:308

}

// targetShards returns either all shards or a single one, depending on the value of the shard parameter.
func (r *singleTenantRouter) targetShards(collection, shardName string) ([]string, error) {
	if shardName == "" {
		return r.schemaReader.Shards(collection)
	}

	// Membership check only — avoids Shards' sorted copy of the full shard list on every routing-plan build.
	found := false
	err := r.schemaReader.Read(collection, true, func(_ *models.Class, state *sharding.State) error {
		_, found = state.Physical[shardName]
		return nil
	})
	if err != nil {
		return nil, err
	}
	if !found {
		return nil, fmt.Errorf("error while trying to find shard: %s in collection: %s", shardName, collection)
	}
	return []string{shardName}, nil
}

// readReplicasForShard gathers only read replicas for one shard.
func (r *singleTenantRouter) readReplicasForShard(collection, tenant, shard string) ([]types.Replica, error) {
	replicas, err := r.schemaReader.ShardReplicas(collection, shard)
	if err != nil {
		return nil, fmt.Errorf("error while getting replicas for collection %q shard %q: %w", collection, shard, err)
	}

	readNodeNames := r.replicationFSMReader.FilterOneShardReplicasRead(collection, shard, replicas)
	return buildReplicas(readNodeNames, shard, r.nodeSelector.NodeHostname), nil
}

// writeReplicasForShard gathers the write replicas for one shard.
func (r *singleTenantRouter) writeReplicasForShard(collection, tenant, shard string) ([]types.Replica, error) {
	replicas, err := r.schemaReader.ShardReplicas(collection, shard)

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. List actual shards (GET /v1/schema/{class}/shards) and use an existing shard name.
2. Verify tenant vs shard semantics: for MT collections use the tenant name; do not confuse tenant with physical shard.
3. Refresh schema/shard caches or reconnect — the shard set may have changed since the client cached it.
4. Recreate the shard/tenant if it was deleted unintentionally.

Example fix

// before
cur, err := client.Schema().Class().ShardGetter().WithShardName("shard-9").Do(ctx) // nonexistent
// after: enumerate first
shards, _ := client.Schema().Class().ShardsGetter().Do(ctx)
// pick a valid shard from shards

shards, err := client.Schema().Class().ShardsGetter().Do(ctx)
if err != nil { return err }
if !slices.Contains(shards, shardName) {
  return fmt.Errorf("shard %q not in collection shards %v", shardName, shards)
}

if strings.Contains(err.Error(), "error while trying to find shard") {
  // re-list shards and pick a valid one, or recreate the tenant/shard
}

When it happens

Trigger: Directing a read/write at a shard name that does not exist for the collection — wrong shard name, shard deleted, tenant name used as shard name on a non-partitioned collection, or collection recreated with a different partitioning.

Common situations: Hand-built shard/tenant routing in scripts; requests after a tenant was offboarded and its shard removed; typos in shard identifiers; stale caches of shard names after a schema update.

Related errors

• shard not found
• backup blocked: runtime-reindex in flight on this shard
• local %s shard does not exist
• delete remote object: shard=%q: %w
• failed to locally execute read plan on replica %s: %w

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