weaviate/weaviate · warning · ErrUnprocessable

local %s shard does not exist

Error message

local %s shard does not exist

What it means

The coordinator node asked to search a shard by name, but GetShard returned no local shard for it. The node cannot serve the request and returns an ErrUnprocessable (HTTP 422), signalling a state mismatch: the request targets a shard that is not (or no longer) hosted on this node.

Source

Thrown at adapters/repos/db/index.go:2961

	}
	if additional.QueryProfile {
		helpers.AddShardQueryProfile(ctx, shard.ID(), i.getSchema.NodeName(), "vector", time.Since(shardStart), helpers.ExtractSlowQueryDetails(ctx))
	}
	return res, resDists, nil
}

func (i *Index) localShardSearch(ctx context.Context, searchVectors []models.Vector,
	targetVectors []string, dist float32, limit int, localFilters *filters.LocalFilter,
	sort []filters.Sort, groupBy *searchparams.GroupBy, additionalProps additional.Properties,
	targetCombination *dto.TargetCombination, properties []string, tenantName string, shardName string,
) ([]*storobj.Object, []float32, error) {
	shard, release, err := i.GetShard(ctx, shardName)
	if err != nil {
		return nil, nil, err
	}
	defer release()
	if shard == nil {
		return nil, nil, enterrors.NewErrUnprocessable(fmt.Errorf("local %s shard does not exist", shardName))
	}

	localCtx := helpers.InitSlowQueryDetails(ctx)
	helpers.AnnotateSlowQueryLog(localCtx, "is_coordinator", true)
	var shardStart time.Time
	if additionalProps.QueryProfile {
		shardStart = time.Now()
	}
	localShardResult, localShardScores, err := shard.ObjectVectorSearch(
		localCtx, searchVectors, targetVectors, dist, limit, localFilters, sort, groupBy, additionalProps, targetCombination, properties)
	if err != nil {
		return nil, nil, errors.Wrapf(err, "shard %s", shard.ID())
	}
	if additionalProps.QueryProfile {
		helpers.AddShardQueryProfile(ctx, shard.ID(), i.getSchema.NodeName(), "vector", time.Since(shardStart), helpers.ExtractSlowQueryDetails(localCtx))
	}
	// Append result to out
	if i.shardHasMultipleReplicasRead(tenantName, shardName) {

View on GitHub (pinned to 75aa4b6d11)

Solutions

  1. Check the tenant status (GET /v1/schema/{class}/tenants) — activate or upload the tenant if it is OFFLOADED/COLD
  2. Send the query to a node that hosts the shard, or let the load balancer/cluster client route correctly
  3. Wait for shard creation/migration to complete after activating a tenant, then retry
  4. If the shard should exist here but doesn't, trigger a replica recovery/rebalance or re-create the tenant from backup

Example fix

// before
await client.collections.get('Orders').query().bm25('term') // tenant offloaded
// after
const tenants = await client.collections.get('Orders').tenants.get();
if (tenants['tenant-1'].tenantStatus === 'OFFLOADED') {
  await client.collections.get('Orders').tenants.update({name:'tenant-1', tenantStatus:'ACTIVE'});
}
await client.collections.get('Orders').query().bm25('term');
Defensive patterns

Strategy: validation

Validate before calling

const tenants = await client.collections.get('Orders').tenants.get();
if (tenants['tenant-1'].tenantStatus !== 'ACTIVE') {
  await client.collections.get('Orders').tenants.update({name:'tenant-1', tenantStatus:'ACTIVE'});
}

Type guard

function isShardMissingError(e) {
  return e instanceof Error && /local .* shard does not exist/.test(e.message);
}

Try / catch

try {
  return await tenantClient.query().bm25('term').do();
} catch (e) {
  if (/shard does not exist/.test(e.message) || e.status === 422) {
    await activateTenant('tenant-1'); // then retry once
    return await tenantClient.query().bm25('term').do();
  }
  throw e;
}

Prevention

When it happens

Trigger: Querying a tenant whose shard was moved to another node (tenant not active here), an offloaded/deactivated tenant, a shard not yet created after tenant activation, or a stale routing decision after rebalancing.

Common situations: Multi-tenancy: querying a tenant in COLD/OFFLOADED status without auto-offloading handles; querying a node that no longer hosts the tenant after shard migration; race between tenant creation/activation and the first query.

Related errors

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