{"record":{"id":"6d5b54df7c4dd43e","repo":"aeron-io/aeron","slug":"failed-to-write-remove-rcv-destination-command","errorCode":null,"errorMessage":"failed to write remove rcv destination command","messagePattern":"failed to write remove rcv destination command","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/DriverProxy.java","lineNumber":345,"sourceCode":"\n        return correlationId;\n    }\n\n    /**\n     * Remove a destination from the receive channel endpoint of an existing MDS Subscription.\n     *\n     * @param registrationId  of the Subscription.\n     * @param endpointChannel used for the {@link #addRcvDestination(long, String)} command.\n     * @return the correlation id for the command.\n     */\n    public long removeRcvDestination(final long registrationId, final String endpointChannel)\n    {\n        final long correlationId = toDriverCommandBuffer.nextCorrelationId();\n        final int length = DestinationMessageFlyweight.computeLength(endpointChannel.length());\n        final int index = toDriverCommandBuffer.tryClaim(REMOVE_RCV_DESTINATION, length);\n        if (index < 0)\n        {\n            throw new AeronException(\"failed to write remove rcv destination command\");\n        }\n\n        destinationMessageFlyweight\n            .wrap(toDriverCommandBuffer.buffer(), index)\n            .registrationCorrelationId(registrationId)\n            .channel(endpointChannel)\n            .clientId(clientId)\n            .correlationId(correlationId);\n\n        toDriverCommandBuffer.commit(index);\n\n        return correlationId;\n    }\n\n    /**\n     * Add a new counter with a type id plus the label and key are provided in buffers.\n     *\n     * @param typeId      for associating with the counter.","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DriverProxy.java#L327-L363","documentation":"DriverProxy.removeRcvDestination claims space in the toDriverCommandBuffer to write a REMOVE_RCV_DESTINATION command. A negative tryClaim return means the ring buffer had no room for the message, so the command was never enqueued and AeronException is thrown. This indicates client-to-driver command backpressure or a non-consuming driver.","triggerScenarios":"Calling Subscription.removeRcvDestination when the driver command ring is full — driver dead, paused (GC/debugger), or the client issued many commands in a tight loop faster than the driver drains.","commonSituations":"Driver terminated while client teardown code removes MDC destinations; bulk removal of many destinations in shutdown code; embedded driver agent thread blocked, leaving the command queue saturated.","solutions":["Confirm the media driver is alive and its agent thread is consuming commands","Retry removeRcvDestination after a short backoff if the driver is only momentarily slow","Throttle bulk destination removals (e.g., small sleep or batching between calls)","For embedded drivers, ensure the driver agent thread is not blocked and enlarge the command queue if consistently saturated","Treat repeated failures as driver death: close the client and reconnect/restart the driver"],"exampleFix":"// before\nsubscription.removeRcvDestination(channel);\n// after\nif (!driverProxy.isActive()) throw new IllegalStateException(\"driver stopped\");\nawaitCommandBufferDrained(); // ensure ring has capacity before claiming\nsubscription.removeRcvDestination(channel);","handlingStrategy":"retry","validationCode":"if (!aeron.context().isDriverActive()) {\n    throw new IllegalStateException(\"driver inactive; removeRcvDestination would fail\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    subscription.removeRcvDestination(channel);\n} catch (AeronException e) {\n    if (!e.getMessage().startsWith(\"failed to write\")) throw e;\n    // retry with backoff; abort after N attempts\n}","preventionTips":["Verify driver health before teardown bursts","Stagger bulk destination removal during shutdown","Keep control-command churn low on active subscriptions","In tests, stop publications/subscriptions before stopping the driver","Track claim-failure counts as a driver-stall signal"],"tags":["aeron","ipc","backpressure","media-driver"],"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"}