{"record":{"id":"353dd52ec2f75db1","repo":"apache/druid","slug":"s-dynamic-msg-passed-to-druidexception-defensive","errorCode":null,"errorMessage":"%s (dynamic msg passed to DruidException.defensive)","messagePattern":"(.+?) \\(dynamic msg passed to DruidException\\.defensive\\)","errorType":"error_code","errorClass":"DruidException","httpStatus":500,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/error/DruidException.java","lineNumber":205,"sourceCode":"   */\n  public static DruidException defensive(Throwable cause, String format, Object... args)\n  {\n    return defensive().build(cause, format, args);\n  }\n\n  /**\n   * Build a \"defensive\" exception, this is an exception that should never actually be triggered. Throw to\n   * allow messages to be seen by developers\n   *\n   * @param condition - boolean condition to validate\n   * @param msg - passed through to InvalidInput.exception()\n   * @param args - passed through to InvalidInput.exception()\n   */\n  @SuppressWarnings(\"unused\")\n  public static void conditionalDefensive(boolean condition, String msg, Object... args)\n  {\n    if (!condition) {\n      throw defensive(msg, args);\n    }\n  }\n\n  private final Persona targetPersona;\n  private final Category category;\n  private final String errorCode;\n  protected final Map<String, String> context = new LinkedHashMap<>();\n\n  private DruidException(\n      Throwable cause,\n      final String errorCode,\n      Persona targetPersona,\n      Category category,\n      final String message\n  )\n  {\n    this(cause, errorCode, targetPersona, category, message, false);\n  }","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/error/DruidException.java#L187-L223","documentation":"DruidException.conditionalDefensive(condition, msg, args) throws a 'defensive' DruidException when the condition is false. Defensive exceptions mark internal invariants that should never be violated; if you see one, it indicates a bug or misuse of an internal API rather than an expected user-facing failure. The generic message text shown here is a placeholder — the real message is the dynamic msg argument passed at each call site.","triggerScenarios":"Calling any Druid API that internally calls DruidException.conditionalDefensive(cond, ...) where cond evaluates to false — i.e., an internal precondition/invariant check failed.","commonSituations":"Bugs in Druid or extension code hitting an impossible state; misuse of internal APIs from custom extensions; race conditions or corrupted inputs violating assumed invariants.","solutions":["Read the actual dynamic message in the exception — it names the violated condition.","Capture the full stack trace and file a Druid bug with reproduction steps if the inputs are valid.","Check your extension/custom code for misuse of internal Druid APIs.","Upgrade to a newer Druid version where the invariant bug may already be fixed."],"exampleFix":"// before: ignoring an unexpected state\nhandler.process(state); // state may be invalid\n// after: validate inputs and report violations as bugs\nif (state == null) {\n  throw new IllegalArgumentException(\"state required\");\n}\nhandler.process(state);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { druidInternalCall(args); } catch (DruidException e) {\n  if (e.getPersona() == DruidException.Persona.DEVELOPER) {\n    // defensive violation: capture for a bug report\n    log.error(\"Druid invariant violated\", e);\n  }\n  throw e;\n}","preventionTips":["Treat defensive exceptions as Druid bugs: file a report with the full message and stack trace.","Keep Druid and extensions on compatible, up-to-date versions.","Do not call Druid internal APIs from custom code without matching version contracts.","Record the exact dynamic message — it pinpoints the violated condition."],"tags":["internal-invariant","defensive-check","bug"],"backgroundTag":"internal-invariant-violation","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"}