{"id":"50e2781766406e30","repo":"apache/kafka","slug":"the-exception-passed-to-raise-must-not-be-null","errorCode":null,"errorMessage":"The exception passed to raise must not be null","messagePattern":"The exception passed to raise must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/RequestFuture.java","lineNumber":144,"sourceCode":"\n            if (!result.compareAndSet(INCOMPLETE_SENTINEL, value))\n                throw new IllegalStateException(\"Invalid attempt to complete a request future which is already complete\");\n            fireSuccess();\n        } finally {\n            completedLatch.countDown();\n        }\n    }\n\n    /**\n     * Raise an exception. The request will be marked as failed, and the caller can either\n     * handle the exception or throw it.\n     * @param e corresponding exception to be passed to caller\n     * @throws IllegalStateException if the future has already been completed\n     */\n    public void raise(RuntimeException e) {\n        try {\n            if (e == null)\n                throw new IllegalArgumentException(\"The exception passed to raise must not be null\");\n\n            if (!result.compareAndSet(INCOMPLETE_SENTINEL, e))\n                throw new IllegalStateException(\"Invalid attempt to complete a request future which is already complete\");\n\n            fireFailure();\n        } finally {\n            completedLatch.countDown();\n        }\n    }\n\n    /**\n     * Raise an error. The request will be marked as failed.\n     * @param error corresponding error to be passed to caller\n     */\n    public void raise(Errors error) {\n        raise(error.exception());\n    }\n","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/RequestFuture.java#L126-L162","documentation":"Thrown by RequestFuture.raise(RuntimeException e) when e is null. The future stores the exception directly as its result and later returns it from exception(); a null result would alias INCOMPLETE_SENTINEL-style bugs and make failed()/exception() inconsistent. raise() therefore requires a non-null RuntimeException so the failure state is always observable.","triggerScenarios":"Calling future.raise(null); passing the result of a method that can return null (e.g. some Errors.exception() variants or a lookup that returned null) without a null check; calling raise(error.exception()) where error is null.","commonSituations":"Static analysis or refactors that surface a previously-unreachable null path; helper methods that translate Errors into exceptions returning null for an unknown code; defensive code that catches Throwable and passes the (possibly null) cause into raise().","solutions":["Ensure the exception passed to raise() is non-null; guard with if (e != null) future.raise(e).","If translating from org.apache.kafka.common.protocol.Errors, use future.raise(error) (the Errors overload) which never produces null.","Replace null failure causes with an explicit IllegalStateException(\"unknown failure\") so the failure is observable."],"exampleFix":"// before\nRuntimeException e = lookupException(code); // may return null\nfuture.raise(e); // throws if e == null\n\n// after\nRuntimeException e = lookupException(code);\nfuture.raise(e != null ? e : new IllegalStateException(\"unknown error code \" + code));","handlingStrategy":"validation","validationCode":"// Before calling raise(e), ensure the exception is non-null.\nif (e == null) {\n    throw new IllegalArgumentException(\"raise() requires a non-null exception\");\n}\nfuture.raise(e);\n// Or use the Errors overload which cannot be null: future.raise(Errors.XXX);","typeGuard":"java.util.function.BiConsumer<RequestFuture<?>, RuntimeException> safeRaise = (f, e) -> {\n    if (e == null) {\n        throw new IllegalArgumentException(\"exception must not be null\");\n    }\n    f.raise(e);\n};","tryCatchPattern":"try {\n    future.raise(e);\n} catch (IllegalArgumentException ex) {\n    // e was null; supply a concrete failure\n    future.raise(new org.apache.kafka.common.errors.UnknownServerException());\n}","preventionTips":["Prefer the raise(Errors) overload — Errors is an enum and cannot be null.","Annotate exception sources with @NonNull / Objects.requireNonNull before they reach raise().","Never derive the exception from a lookup (Errors.get(code)) without checking the result."],"tags":["consumer","async","future-state","null-safety"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}