{"record":{"id":"2768efa9e0818fff","repo":"thanos-io/thanos","slug":"query-not-explainable","errorCode":null,"errorMessage":"Query not explainable","messagePattern":"Query not explainable","errorType":"validation","errorClass":"api.ApiError","httpStatus":400,"severity":"error","filePath":"pkg/api/query/v1.go","lineNumber":438,"sourceCode":"\t}\n\n\tif len(data) == 0 {\n\t\treturn nil, nil\n\t}\n\n\tvar info storepb.ShardInfo\n\tif err := json.Unmarshal([]byte(data), &info); err != nil {\n\t\treturn nil, &api.ApiError{Typ: api.ErrorBadData, Err: errors.Wrapf(err, \"could not unmarshal parameter %s\", ShardInfoParam)}\n\t}\n\n\treturn &info, nil\n}\n\nfunc (qapi *QueryAPI) getQueryExplain(query promql.Query) (*engine.ExplainOutputNode, *api.ApiError) {\n\tif eq, ok := query.(engine.ExplainableQuery); ok {\n\t\treturn eq.Explain(), nil\n\t}\n\treturn nil, &api.ApiError{Typ: api.ErrorBadData, Err: errors.Errorf(\"Query not explainable\")}\n}\n\nfunc (qapi *QueryAPI) parseQueryAnalyzeParam(r *http.Request) bool {\n\treturn (r.FormValue(QueryAnalyzeParam) == \"true\" || r.FormValue(QueryAnalyzeParam) == \"1\")\n}\n\nfunc analyzeQueryOutput(query promql.Query, engineType PromqlEngineType, tracker *fanout.Tracker) (queryTelemetry, error) {\n\tif eq, ok := query.(engine.ExplainableQuery); ok {\n\t\tif analyze := eq.Analyze(); analyze != nil {\n\t\t\treturn processAnalysis(analyze, tracker), nil\n\t\t} else {\n\t\t\treturn queryTelemetry{}, errors.Errorf(\"Query: %v not analyzable\", query)\n\t\t}\n\t}\n\n\tvar warning error\n\tif engineType == PromqlEngineThanos {\n\t\twarning = errors.New(\"Query fallback to prometheus engine; not analyzable.\")","sourceCodeStart":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/api/query/v1.go#L420-L456","documentation":"getQueryExplain returns an HTTP 400 (api.ErrorBadData) when the promql.Query object returned by the engine does not implement engine.ExplainableQuery, so Explain() cannot be called. This happens when the query was executed by an engine whose query type lacks explain support (e.g. the plain Prometheus engine instead of the Thanos engine).","triggerScenarios":"Calling the query_explain endpoint (queryExplain/queryRangeExplain) while the effective engine is not the Thanos engine, so the returned query cannot be type-asserted to engine.ExplainableQuery.","commonSituations":"Older Thanos builds or deployments where the promql engine fallback is active; clients hitting explain endpoints after the engine was switched to 'prometheus'.","solutions":["Pass `engine=thanos` in the request so the query runs on the explainable Thanos engine.","Upgrade Thanos to a version where the Thanos engine supports Explain on all query paths.","Remove explain calls from clients when using the Prometheus engine, since it does not support explain."],"exampleFix":"// before\nGET /api/v1/query_explain?query=up&engine=prometheus\n// after\nGET /api/v1/query_explain?query=up&engine=thanos","handlingStrategy":"try-catch","validationCode":"if (engine && engine !== 'thanos') {\n  throw new Error('query_explain requires engine=thanos');\n}","typeGuard":null,"tryCatchPattern":"const body = await res.json();\nif (body.status === 'error' && body.error === 'Query not explainable') {\n  // fall back to a normal query without explain, or switch engine=thanos\n}","preventionTips":["Only call explain endpoints against Thanos-engine deployments.","Always send engine=thanos explicitly with explain requests.","Check your Thanos version supports ExplainableQuery before relying on explain."],"tags":["http-api","promql","explain","type-assertion"],"backgroundTag":"unsupported-operation","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}