{"record":{"id":"f06068f28bad051d","repo":"weaviate/weaviate","slug":"v-f06068","errorCode":null,"errorMessage":"%v","messagePattern":"%v","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"adapters/handlers/rest/clusterapi/indices.go","lineNumber":1321,"sourceCode":"\t\t}\n\n\t\ttargetStatus, err := shared.IndicesPayloads.UpdateShardStatusParams.\n\t\t\tUnmarshal(reqPayload)\n\t\tif err != nil {\n\t\t\thttp.Error(w, \"unmarshal find doc ids params from json: \"+err.Error(),\n\t\t\t\thttp.StatusBadRequest)\n\t\t\treturn\n\t\t}\n\n\t\tschemaVersion, err := extractSchemaVersionFromUrlQuery(r.URL.Query())\n\t\tif err != nil {\n\t\t\thttp.Error(w, err.Error(), http.StatusBadRequest)\n\t\t\treturn\n\t\t}\n\n\t\terr = i.shards.UpdateShardStatus(r.Context(), index, shard, targetStatus, schemaVersion)\n\t\tif err != nil {\n\t\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t\t\treturn\n\t\t}\n\t})\n}\n\nfunc (i *indices) postShardFile() http.Handler {\n\treturn http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n\t\targs := i.regexpShardFiles.FindStringSubmatch(r.URL.Path)\n\t\tif len(args) != 4 {\n\t\t\thttp.Error(w, \"invalid URI\", http.StatusBadRequest)\n\t\t\treturn\n\t\t}\n\n\t\tindex, shard, filename := args[1], args[2], args[3]\n\n\t\tct, ok := shared.IndicesPayloads.ShardFiles.CheckContentTypeHeaderReq(r)\n\t\tif !ok {\n\t\t\thttp.Error(w, errors.Errorf(\"unexpected content type: %s\", ct).Error(),","sourceCodeStart":1303,"sourceCodeEnd":1339,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/handlers/rest/clusterapi/indices.go#L1303-L1339","documentation":"The actual status transition is performed by i.shards.UpdateShardStatus with the parsed index, shard, target status, and schema version. Any error returned here is written as a 500 with the raw error text. At this point input validation has passed, so the failure is on the storage/consistency side: shard not found locally, shard in a conflicting lifecycle state, or a schema-version consistency check failing during replication.","triggerScenarios":"POST update-shard-status where the local node cannot apply the requested state transition — shard does not exist on this node, store is closing, the target state conflicts with the current state, or the schema-version propagation fails.","commonSituations":"Requests routed to nodes not hosting the shard; concurrent status updates racing (e.g. readonly set while shard is shutting down); shard replacement/replica-move in progress; schema out of sync between nodes.","solutions":["Ensure the request targets a node that hosts the shard (check shard distribution)","Check node logs for the underlying UpdateShardStatus error text","Retry the transition after any concurrent shard operation (backup, replica move) completes","Re-sync schema state across nodes if version consistency errors appear"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// confirm the node hosts the shard and the transition is legal\nif !nodeHasShard(index, shard) {\n\treturn fmt.Errorf(\"shard %s/%s not on this node\", index, shard)\n}\nif current == target {\n\treturn nil // no-op, skip the call\n}","typeGuard":null,"tryCatchPattern":"err := client.UpdateShardStatus(ctx, index, shard, target, sv)\nif err != nil {\n\tlog.Warnf(\"update shard status failed: %v\", err)\n\tif isConflict(err) { return refreshSchemaAndRetry() }\n\treturn backoffRetry(err)\n}","preventionTips":["Verify shard placement before sending status transitions","Avoid concurrent transitions on the same shard (backups, replica moves)","Refresh schema after topology changes before issuing updates","Read the 500 body — it carries the specific storage-side error"],"tags":["http","clusterapi","shard-lifecycle","internal-server-error"],"backgroundTag":"shard-state-transition-failed","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"}