apache/druid · error · ISE

%s is an unknown multi stage query mode. Acceptable modes: %

Error message

%s is an unknown multi stage query mode. Acceptable modes: %s

What it means

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'.

Source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/sql/MSQMode.java:71

    for (MSQMode msqMode : MSQMode.values()) {
      if (msqMode.value.equalsIgnoreCase(str)) {
        return msqMode;
      }
    }
    return null;
  }

  @Override
  public String toString()
  {
    return value;
  }

  public static void populateDefaultQueryContext(final String modeStr, final Map<String, Object> originalQueryContext)
  {
    MSQMode mode = MSQMode.fromString(modeStr);
    if (mode == null) {
      throw new ISE(
          "%s is an unknown multi stage query mode. Acceptable modes: %s",
          modeStr,
          Arrays.stream(MSQMode.values()).map(m -> m.value).collect(Collectors.toList())
      );
    }
    log.debug("Populating default query context with %s for the %s multi stage query mode", mode.defaultQueryContext, mode);
    QueryContexts.addDefaults(originalQueryContext, mode.defaultQueryContext);
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set 'mode' to one of the listed acceptable values in the error message (case-sensitive).
2. Remove the 'mode' context key entirely to use engine defaults.
3. Check the Druid documentation for your version to see which MSQ modes are supported.
4. Fix the client/library configuration that injects the mode value.

Example fix

// before
final Map<String, Object> ctx = Map.of("mode", "paralell");

// after
final Map<String, Object> ctx = Map.of("mode", "parallel");

// validate the mode context value before submitting
final java.util.Set<String> valid = java.util.Set.of("sequential", "parallel", "maxParallelism");
Object mode = queryContext.get("mode");
if (mode != null && !valid.contains(String.valueOf(mode))) {
  throw new IllegalArgumentException("mode must be one of " + valid + ", got: " + mode);
}

try {
  client.submit(query);
} catch (DruidException e) {
  if (e.getMessage().contains("unknown multi stage query mode")) {
    queryContext.remove("mode"); // fall back to engine default
    client.submit(query);
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• No such outputChannelMode[%s]
• Expected key [%s] to be referring to one of the values [%s]
• Cannot have empty worker set
• Can not supply empty segments as input, please use either nu
• Partition count must be at least 1

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/5d55a14a21ff1554. Report an issue: GitHub.