{"record":{"id":"396fdb4d1e4efc05","repo":"apache/druid","slug":"cannot-set-both-realtimesegmentsmode-and-depreca","errorCode":null,"errorMessage":"Cannot set both [realtimeSegmentsMode] and deprecated [realtimeSegmentsOnly]; use [realtimeSegmentsMode] only.","messagePattern":"Cannot set both \\[realtimeSegmentsMode\\] and deprecated \\[realtimeSegmentsOnly\\]; use \\[realtimeSegmentsMode\\] only\\.","errorType":"validation","errorClass":"BadQueryContextException","httpStatus":400,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/query/QueryContext.java","lineNumber":800,"sourceCode":"    return getBoolean(QueryContexts.CTX_PREPLANNED, QueryContexts.DEFAULT_PREPLANNED);\n  }\n\n  /**\n   * Returns the realtime segments mode for this query. If {@link QueryContexts#REALTIME_SEGMENTS_MODE} is absent\n   * or null, falls back to the deprecated {@code realtimeSegmentsOnly} boolean: {@code true} maps\n   * to {@link RealtimeSegmentsMode#EXCLUSIVE}; otherwise returns {@link RealtimeSegmentsMode#INCLUDE}.\n   * Throws {@link BadQueryContextException} if both fields are set simultaneously.\n   */\n  public RealtimeSegmentsMode getRealtimeSegmentsMode()\n  {\n    RealtimeSegmentsMode mode = getEnum(\n        QueryContexts.REALTIME_SEGMENTS_MODE,\n        RealtimeSegmentsMode.class,\n        null\n    );\n    boolean hasDeprecatedFlag = get(QueryContexts.REALTIME_SEGMENTS_ONLY) != null;\n    if (mode != null && hasDeprecatedFlag) {\n      throw new BadQueryContextException(\n          StringUtils.format(\n              \"Cannot set both [%s] and deprecated [%s]; use [%s] only.\",\n              QueryContexts.REALTIME_SEGMENTS_MODE,\n              QueryContexts.REALTIME_SEGMENTS_ONLY,\n              QueryContexts.REALTIME_SEGMENTS_MODE\n          )\n      );\n    }\n    if (mode != null) {\n      return mode;\n    }\n    if (hasDeprecatedFlag) {\n      // Backward-compat: honour the deprecated realtimeSegmentsOnly flag.\n      return getBoolean(QueryContexts.REALTIME_SEGMENTS_ONLY, QueryContexts.DEFAULT_REALTIME_SEGMENTS_ONLY)\n             ? RealtimeSegmentsMode.EXCLUSIVE\n             : QueryContexts.DEFAULT_REALTIME_SEGMENTS_MODE;\n    }\n    return QueryContexts.DEFAULT_REALTIME_SEGMENTS_MODE;","sourceCodeStart":782,"sourceCodeEnd":818,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/QueryContext.java#L782-L818","documentation":"QueryContext validates that the new 'realtimeSegmentsMode' context key and the deprecated boolean 'realtimeSegmentsOnly' key are not both present. Because the old flag was superseded by the mode enum, setting both is ambiguous, so Druid throws BadQueryContextException rather than guessing precedence. This is an explicit configuration-conflict guard during query context parsing.","triggerScenarios":"Submitting a query whose context map (or SQL query context parameters) contains both 'realtimeSegmentsMode' (any non-null value) and 'realtimeSegmentsOnly' (any non-null value). The check runs in QueryContext when resolving REALTIME_SEGMENTS_MODE.","commonSituations":"Clients built against older Druid versions still sending realtimeSegmentsOnly while the application was upgraded to also set realtimeSegmentsMode; dashboard/BI tools injecting the legacy flag on top of new context; copy-pasted query templates accumulating both keys.","solutions":["Remove the deprecated 'realtimeSegmentsOnly' key from the query context and keep only 'realtimeSegmentsMode'.","If both keys come from different layers, find which client/template sets realtimeSegmentsOnly and update or delete it.","Map the legacy boolean to the equivalent realtimeSegmentsMode enum value and express it purely via the mode key.","Audit context construction code for both QueryContexts constants if you control the caller."],"exampleFix":"// before\nMap<String, Object> context = Map.of(\n    QueryContexts.REALTIME_SEGMENTS_ONLY, true,\n    QueryContexts.REALTIME_SEGMENTS_MODE, \"AUTO\"\n);\n// after\nMap<String, Object> context = Map.of(\n    QueryContexts.REALTIME_SEGMENTS_MODE, \"AUTO\"\n);","handlingStrategy":"validation","validationCode":"if (context.containsKey(\"realtimeSegmentsMode\") && context.containsKey(\"realtimeSegmentsOnly\")) {\n  throw new IllegalArgumentException(\"Set only 'realtimeSegmentsMode'; 'realtimeSegmentsOnly' is deprecated\");\n}","typeGuard":"boolean hasConflictingContextKeys(Map<String, Object> ctx) {\n  return ctx.get(\"realtimeSegmentsMode\") != null && ctx.get(\"realtimeSegmentsOnly\") != null;\n}","tryCatchPattern":"try {\n  QueryContext qctx = QueryContext.of(context);\n} catch (BadQueryContextException e) {\n  if (e.getMessage().contains(\"realtimeSegmentsOnly\")) {\n    context.remove(\"realtimeSegmentsOnly\");\n    qctx = QueryContext.of(context);\n  } else { throw e; }\n}","preventionTips":["Migrate all clients/templates off realtimeSegmentsOnly when upgrading","Centralize query-context construction in one helper that rejects the legacy key","Strip deprecated keys in a context-normalization layer before submitting queries","Log when the legacy key is encountered so stragglers can be fixed"],"tags":["druid","query-context","configuration-conflict","deprecated-flag"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}