aeron-io/aeron · error · AeronException

failed to write add destination command

Error message

failed to write add destination command

What it means

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.

Solutions

1. Check driver health before dynamic destination changes; retry addDestination after the driver recovers.
2. Reduce churn: batch destination changes instead of issuing many per second.
3. Verify the publication is still open — operations on a closing publication race with conductor shutdown.

Example fix

// before
publication.addDestination("aeron:udp?endpoint=host2:40456");
// after
if (driverIsRunning()) { publication.addDestination("aeron:udp?endpoint=host2:40456"); }
else { scheduleRetry("aeron:udp?endpoint=host2:40456"); }

if (aeron.isClosed() || !driverIsAlive()) {
    throw new IllegalStateException("cannot addDestination: driver unavailable");
}

null

try {
    publication.addDestination(endpointChannel);
} catch (AeronException e) {
    log.error("addDestination command not delivered", e);
    pendingDestinations.add(endpointChannel); // replay when driver recovers
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to write remove destination command
• failed to write add publication command
• failed to write add exclusive publication command
• failed to write remove publication command
• failed to write add subscription command

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/8c438622796663ad. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/DriverProxy.java:229

        return correlationId;
    }

    /**
     * Add a destination to the send channel of an existing MDC Publication.
     *
     * @param registrationId  of the Publication.
     * @param endpointChannel for the destination.
     * @return the correlation id for the command.
     */
    public long addDestination(final long registrationId, final String endpointChannel)
    {
        final long correlationId = toDriverCommandBuffer.nextCorrelationId();
        final int length = DestinationMessageFlyweight.computeLength(endpointChannel.length());
        final int index = toDriverCommandBuffer.tryClaim(ADD_DESTINATION, length);
        if (index < 0)
        {
            throw new AeronException("failed to write add destination command");
        }

        destinationMessageFlyweight
            .wrap(toDriverCommandBuffer.buffer(), index)
            .registrationCorrelationId(registrationId)
            .channel(endpointChannel)
            .clientId(clientId)
            .correlationId(correlationId);

        toDriverCommandBuffer.commit(index);

        return correlationId;
    }

    /**
     * Remove a destination from the send channel of an existing MDC Publication.
     *
     * @param registrationId  of the Publication.

View on GitHub (pinned to 6d60124e15)