apache/druid · error · IllegalStateException

Unknown strategy[ ], query id [ ]

Error message

Unknown strategy[%s], query id [%s]

What it means

SearchStrategySelector.strategize() dispatches on the 'searchStrategy' query parameter; an unrecognized value falls through the switch and throws ISE('Unknown strategy[...], query id [...]'). Druid supports only a fixed set of strategies (e.g. use-index, cursor-only). A misspelled or unavailable strategy name in the query context triggers it.

Solutions

1. Set searchStrategy to a valid value such as 'use-index' or 'cursor-only', or remove the key to use auto-selection
2. Check the Druid version's supported strategy names (SearchStrategySelector switch)
3. Correct typos in the query context key/value

Example fix

// before
{"searchStrategy": "index-only"}
// after
{"searchStrategy": "use-index"} // or omit to let Druid choose

Set.of("use-index","cursor-only").contains(context.get("searchStrategy")) // validate before submitting

boolean isValidSearchStrategy(Object v) { return v == null || v instanceof String && Set.of("use-index","cursor-only").contains(v); }

try { runner.search(query); } catch (ISE e) { if (e.getMessage().startsWith("Unknown strategy")) { retryWithoutSearchStrategyContext(); } else throw e; }

When it happens

Trigger: Setting searchStrategy to a typo'd or unsupported value in the query context; using a strategy name removed or renamed in a newer Druid version; programmatic context maps with invalid values.

Common situations: Copying query snippets with outdated strategy names; clients passing arbitrary tuning keys expecting them to be ignored; version upgrades renaming strategies.

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

• Can only handle [ ], got [ ]
• Cannot create query type helper from invalid type
• Cannot set both [realtimeSegmentsMode] and deprecated…
• Configured maxScatterGatherBytes =
• Configured timeout =

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/query/search/SearchStrategySelector.java:52

  {
    this.config = configSupplier.get();
  }

  public SearchStrategy strategize(SearchQuery query)
  {
    final String strategyString = config.withOverrides(query).getSearchStrategy();

    switch (strategyString) {
      case "auto":
        log.debug("Auto strategy is selected but has been removed, using 'use-index' strategy instead for query id [%s]", query.getId());
      case UseIndexesStrategy.NAME:
        log.debug("Use-index strategy is selected, query id [%s]", query.getId());
        return UseIndexesStrategy.of(query);
      case CursorOnlyStrategy.NAME:
        log.debug("Cursor-only strategy is selected, query id [%s]", query.getId());
        return CursorOnlyStrategy.of(query);
      default:
        throw new ISE("Unknown strategy[%s], query id [%s]", strategyString, query.getId());
    }
  }
}

View on GitHub (pinned to 9b90983fd2)