{"record":{"id":"5d55a14a21ff1554","repo":"apache/druid","slug":"s-is-an-unknown-multi-stage-query-mode-acceptabl","errorCode":null,"errorMessage":"%s is an unknown multi stage query mode. Acceptable modes: %s","messagePattern":"(.+?) is an unknown multi stage query mode\\. Acceptable modes: (.+?)","errorType":"validation","errorClass":"ISE","httpStatus":null,"severity":"error","filePath":"multi-stage-query/src/main/java/org/apache/druid/msq/sql/MSQMode.java","lineNumber":71,"sourceCode":"    for (MSQMode msqMode : MSQMode.values()) {\n      if (msqMode.value.equalsIgnoreCase(str)) {\n        return msqMode;\n      }\n    }\n    return null;\n  }\n\n  @Override\n  public String toString()\n  {\n    return value;\n  }\n\n  public static void populateDefaultQueryContext(final String modeStr, final Map<String, Object> originalQueryContext)\n  {\n    MSQMode mode = MSQMode.fromString(modeStr);\n    if (mode == null) {\n      throw new ISE(\n          \"%s is an unknown multi stage query mode. Acceptable modes: %s\",\n          modeStr,\n          Arrays.stream(MSQMode.values()).map(m -> m.value).collect(Collectors.toList())\n      );\n    }\n    log.debug(\"Populating default query context with %s for the %s multi stage query mode\", mode.defaultQueryContext, mode);\n    QueryContexts.addDefaults(originalQueryContext, mode.defaultQueryContext);\n  }\n}\n","sourceCodeStart":53,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/multi-stage-query/src/main/java/org/apache/druid/msq/sql/MSQMode.java#L53-L81","documentation":"MSQMode.populateDefaultQueryContext validates the user-supplied 'mode' query context value via MSQMode.fromString; if it does not match any known mode (e.g. 'sequential', 'parallel', 'maxParallelism' depending on version), this ISE is thrown listing the acceptable values. It is input validation of the SQL query context parameter 'mode'.","triggerScenarios":"Submitting a query with context parameter {\"mode\":\"<typo or unsupported value>\"} (e.g. 'Sequential', 'fast', 'paralell') to populateDefaultQueryContext, typically via a SQL statement API request or client library that sets msq mode.","commonSituations":"Typos or wrong casing in the mode string in BI tools or custom clients; copying a mode value from a different Druid version where that mode was added or removed; clients that pass enum names instead of values.","solutions":["Set 'mode' to one of the listed acceptable values in the error message (case-sensitive).","Remove the 'mode' context key entirely to use engine defaults.","Check the Druid documentation for your version to see which MSQ modes are supported.","Fix the client/library configuration that injects the mode value."],"exampleFix":"// before\nfinal Map<String, Object> ctx = Map.of(\"mode\", \"paralell\");\n\n// after\nfinal Map<String, Object> ctx = Map.of(\"mode\", \"parallel\");","handlingStrategy":"validation","validationCode":"// validate the mode context value before submitting\nfinal java.util.Set<String> valid = java.util.Set.of(\"sequential\", \"parallel\", \"maxParallelism\");\nObject mode = queryContext.get(\"mode\");\nif (mode != null && !valid.contains(String.valueOf(mode))) {\n  throw new IllegalArgumentException(\"mode must be one of \" + valid + \", got: \" + mode);\n}","typeGuard":null,"tryCatchPattern":"try {\n  client.submit(query);\n} catch (DruidException e) {\n  if (e.getMessage().contains(\"unknown multi stage query mode\")) {\n    queryContext.remove(\"mode\"); // fall back to engine default\n    client.submit(query);\n  } else { throw e; }\n}","preventionTips":["Centralize query-context construction in one helper with validated constants.","Copy mode values only from the docs matching your Druid version.","Prefer omitting 'mode' unless you specifically need it."],"tags":["msq","query-context","validation","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}