{"record":{"id":"e66bc3f9a21e5719","repo":"aeron-io/aeron","slug":"failed-to-write-reject-image-command","errorCode":null,"errorMessage":"failed to write reject image command","messagePattern":"failed to write reject image command","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/DriverProxy.java","lineNumber":520,"sourceCode":"    /**\n     * Reject a specific image.\n     *\n     * @param imageCorrelationId of the image to be invalidated\n     * @param position      of the image when invalidation occurred\n     * @param reason        user supplied reason for invalidation, reported back to publication\n     * @return              the correlationId of the request for invalidation.\n     */\n    public long rejectImage(\n        final long imageCorrelationId,\n        final long position,\n        final String reason)\n    {\n        final int length = RejectImageFlyweight.computeLength(reason);\n        final int index = toDriverCommandBuffer.tryClaim(REJECT_IMAGE, length);\n\n        if (index < 0)\n        {\n            throw new AeronException(\"failed to write reject image command\");\n        }\n\n        final long correlationId = toDriverCommandBuffer.nextCorrelationId();\n\n        rejectImageFlyweight\n            .wrap(toDriverCommandBuffer.buffer(), index)\n            .clientId(clientId)\n            .correlationId(correlationId)\n            .imageCorrelationId(imageCorrelationId)\n            .position(position)\n            .reason(reason);\n\n        toDriverCommandBuffer.commit(index);\n\n        return correlationId;\n    }\n\n","sourceCodeStart":502,"sourceCodeEnd":538,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DriverProxy.java#L502-L538","documentation":"DriverProxy.rejectImage claims space in the toDriverCommandBuffer to write a REJECT_IMAGE command carrying a reason string. tryClaim returned negative because the ring buffer had no capacity for RejectImageFlyweight.computeLength(reason), so AeronException is thrown and the rejection was never delivered to the driver. Note in this method the correlationId is fetched after the claim, so a failed claim leaves no partial message.","triggerScenarios":"Calling Image.reject(reason) (via DriverProxy.rejectImage) when the client-driver command ring is full: driver dead or stalled, or a burst of control commands (connect/disconnect, destination changes) saturated the queue.","commonSituations":"A subscriber refusing an image during high-churn periods when many control commands are in flight; media driver crashed; driver agent blocked by slow recording (Archive) or a hung MDC destination.","solutions":["Check the media driver is alive and draining the command queue before rejecting images","Retry rejectImage with backoff; capacity returns once the driver catches up","Reduce concurrent control-command bursts around rejection logic","Shorten the reject reason string — smaller messages fit more easily in a nearly-full ring","If the driver is unresponsive, treat the connection as lost and re-establish client and subscription instead of retrying indefinitely"],"exampleFix":"// before\nimage.reject(\"unauthorized stream\");\n// after\ntry {\n    image.reject(\"unauthorized stream\");\n} catch (AeronException e) {\n    if (!driverProxy.isActive()) throw e;\n    Thread.sleep(10);\n    image.reject(\"unauthorized stream\"); // retry once driver drains queue\n}","handlingStrategy":"retry","validationCode":"if (!aeron.context().isDriverActive()) {\n    throw new IllegalStateException(\"driver inactive; image rejection cannot be delivered\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    image.reject(reason);\n} catch (AeronException e) {\n    if (!e.getMessage().startsWith(\"failed to write\")) throw e;\n    // short backoff then retry; if driver is dead, close the subscription instead\n}","preventionTips":["Check driver liveness before rejecting images","Keep reject reason strings short","Avoid rejecting images during heavy control-command churn","On repeated failure, drop the subscription rather than retrying forever","Monitor driver queue drain rate in high-churn systems"],"tags":["aeron","ipc","backpressure","image"],"backgroundTag":"command-buffer-full","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}