{"record":{"id":"8c438622796663ad","repo":"aeron-io/aeron","slug":"failed-to-write-add-destination-command","errorCode":null,"errorMessage":"failed to write add destination command","messagePattern":"failed to write add destination command","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/DriverProxy.java","lineNumber":229,"sourceCode":"\n        return correlationId;\n    }\n\n    /**\n     * Add a destination to the send channel of an existing MDC Publication.\n     *\n     * @param registrationId  of the Publication.\n     * @param endpointChannel for the destination.\n     * @return the correlation id for the command.\n     */\n    public long addDestination(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(ADD_DESTINATION, length);\n        if (index < 0)\n        {\n            throw new AeronException(\"failed to write add 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     * Remove a destination from the send channel of an existing MDC Publication.\n     *\n     * @param registrationId  of the Publication.","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DriverProxy.java#L211-L247","documentation":"DriverProxy.addDestination() throws AeronException when tryClaim(ADD_DESTINATION, length) fails to write the destination command to the client-to-driver ring buffer. This API (used with MDC/SP multi-destination publications, e.g. Publication.addDestination) requires the driver to record the new endpoint; a failed claim means the command was never delivered.","triggerScenarios":"Calling Publication.addDestination(endpointChannel) while the command buffer is full — driver unavailable, blocked, or overwhelmed by other commands. The command length depends on the endpoint channel string length, so very long channel URIs make the full-buffer condition slightly more likely.","commonSituations":"Dynamically adding destinations to a multi-destination publication during a driver outage; rapid topology changes (many add/remove destination calls); driver conductor blocked in a handler.","solutions":["Check driver health before dynamic destination changes; retry addDestination after the driver recovers.","Reduce churn: batch destination changes instead of issuing many per second.","Verify the publication is still open — operations on a closing publication race with conductor shutdown."],"exampleFix":"// before\npublication.addDestination(\"aeron:udp?endpoint=host2:40456\");\n// after\nif (driverIsRunning()) { publication.addDestination(\"aeron:udp?endpoint=host2:40456\"); }\nelse { scheduleRetry(\"aeron:udp?endpoint=host2:40456\"); }","handlingStrategy":"try-catch","validationCode":"if (aeron.isClosed() || !driverIsAlive()) {\n    throw new IllegalStateException(\"cannot addDestination: driver unavailable\");\n}","typeGuard":"null","tryCatchPattern":"try {\n    publication.addDestination(endpointChannel);\n} catch (AeronException e) {\n    log.error(\"addDestination command not delivered\", e);\n    pendingDestinations.add(endpointChannel); // replay when driver recovers\n}","preventionTips":["Check driver health before dynamic destination changes.","Queue and replay destination changes during driver outages.","Keep channel URIs short and valid to minimize command size."],"tags":["aeron","driver-communication","ring-buffer-full","destination-management"],"backgroundTag":"broken-pipe","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"}