{"record":{"id":"8f25b309ef210354","repo":"weaviate/weaviate","slug":"local-s-shard-does-not-exist","errorCode":null,"errorMessage":"local %s shard does not exist","messagePattern":"local (.+?) shard does not exist","errorType":"exception","errorClass":"ErrUnprocessable","httpStatus":422,"severity":"warning","filePath":"adapters/repos/db/index.go","lineNumber":2961,"sourceCode":"\t}\n\tif additional.QueryProfile {\n\t\thelpers.AddShardQueryProfile(ctx, shard.ID(), i.getSchema.NodeName(), \"vector\", time.Since(shardStart), helpers.ExtractSlowQueryDetails(ctx))\n\t}\n\treturn res, resDists, nil\n}\n\nfunc (i *Index) localShardSearch(ctx context.Context, searchVectors []models.Vector,\n\ttargetVectors []string, dist float32, limit int, localFilters *filters.LocalFilter,\n\tsort []filters.Sort, groupBy *searchparams.GroupBy, additionalProps additional.Properties,\n\ttargetCombination *dto.TargetCombination, properties []string, tenantName string, shardName string,\n) ([]*storobj.Object, []float32, error) {\n\tshard, release, err := i.GetShard(ctx, shardName)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tdefer release()\n\tif shard == nil {\n\t\treturn nil, nil, enterrors.NewErrUnprocessable(fmt.Errorf(\"local %s shard does not exist\", shardName))\n\t}\n\n\tlocalCtx := helpers.InitSlowQueryDetails(ctx)\n\thelpers.AnnotateSlowQueryLog(localCtx, \"is_coordinator\", true)\n\tvar shardStart time.Time\n\tif additionalProps.QueryProfile {\n\t\tshardStart = time.Now()\n\t}\n\tlocalShardResult, localShardScores, err := shard.ObjectVectorSearch(\n\t\tlocalCtx, searchVectors, targetVectors, dist, limit, localFilters, sort, groupBy, additionalProps, targetCombination, properties)\n\tif err != nil {\n\t\treturn nil, nil, errors.Wrapf(err, \"shard %s\", shard.ID())\n\t}\n\tif additionalProps.QueryProfile {\n\t\thelpers.AddShardQueryProfile(ctx, shard.ID(), i.getSchema.NodeName(), \"vector\", time.Since(shardStart), helpers.ExtractSlowQueryDetails(localCtx))\n\t}\n\t// Append result to out\n\tif i.shardHasMultipleReplicasRead(tenantName, shardName) {","sourceCodeStart":2943,"sourceCodeEnd":2979,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/index.go#L2943-L2979","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the tenant status (GET /v1/schema/{class}/tenants) — activate or upload the tenant if it is OFFLOADED/COLD","Send the query to a node that hosts the shard, or let the load balancer/cluster client route correctly","Wait for shard creation/migration to complete after activating a tenant, then retry","If the shard should exist here but doesn't, trigger a replica recovery/rebalance or re-create the tenant from backup"],"exampleFix":"// before\nawait client.collections.get('Orders').query().bm25('term') // tenant offloaded\n// after\nconst tenants = await client.collections.get('Orders').tenants.get();\nif (tenants['tenant-1'].tenantStatus === 'OFFLOADED') {\n  await client.collections.get('Orders').tenants.update({name:'tenant-1', tenantStatus:'ACTIVE'});\n}\nawait client.collections.get('Orders').query().bm25('term');","handlingStrategy":"validation","validationCode":"const tenants = await client.collections.get('Orders').tenants.get();\nif (tenants['tenant-1'].tenantStatus !== 'ACTIVE') {\n  await client.collections.get('Orders').tenants.update({name:'tenant-1', tenantStatus:'ACTIVE'});\n}","typeGuard":"function isShardMissingError(e) {\n  return e instanceof Error && /local .* shard does not exist/.test(e.message);\n}","tryCatchPattern":"try {\n  return await tenantClient.query().bm25('term').do();\n} catch (e) {\n  if (/shard does not exist/.test(e.message) || e.status === 422) {\n    await activateTenant('tenant-1'); // then retry once\n    return await tenantClient.query().bm25('term').do();\n  }\n  throw e;\n}","preventionTips":["Check tenant status before querying; only ACTIVE tenants are queryable on their hosting node","Route tenant queries to the node returned by the tenants endpoint (node name in tenant response)","Wait for tenant activation/creation to complete before the first query","Handle 422 responses explicitly in multi-tenant clients instead of treating them as 5xx"],"tags":["multi-tenancy","shard","unprocessable-entity","routing"],"backgroundTag":"shard-does-not-exist","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"}