aeron-io/aeron · error · AeronException

failed to write remove destination command

Error message

failed to write remove destination command

What it means

DriverProxy.removeDestination() throws AeronException when tryClaim(REMOVE_DESTINATION, length) cannot write the removal command to the client-to-driver command buffer. The driver would then keep the endpoint attached, so Aeron throws instead of returning success and silently diverging from driver state.

Solutions

1. Perform destination removal while the driver is confirmed running; defer removals queued during an outage.
2. Wrap removeDestination in try-catch during shutdown paths where driver death is expected.
3. Investigate driver conductor stalls (long handlers, GC pauses) if the buffer repeatedly fills.

Example fix

// before
publication.removeDestination("aeron:udp?endpoint=host2:40456");
// after
try { publication.removeDestination("aeron:udp?endpoint=host2:40456"); }
catch (AeronException e) { log.warn("could not remove destination; driver unavailable", e); }

null

null

try {
    publication.removeDestination(endpointChannel);
} catch (AeronException e) {
    log.warn("removeDestination failed; driver may already be down", e);
}

When it happens

Trigger: Calling Publication.removeDestination(endpointChannel) while the to-driver buffer is full because the driver is stopped, crashed, or its conductor thread is blocked; races with publication close are also possible.

Common situations: Tearing down multi-destination publications during application shutdown after the driver already exited; driver thread wedged on a slow notification handler; network-driven driver restart while clients keep adjusting destinations.

Related errors

• failed to write add 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/f879aabead81fa6a. Report an issue: GitHub.

Appendix: source

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

        return correlationId;
    }

    /**
     * Remove a destination from the send channel of an existing MDC Publication.
     *
     * @param registrationId  of the Publication.
     * @param endpointChannel used for the {@link #addDestination(long, String)} command.
     * @return the correlation id for the command.
     */
    public long removeDestination(final long registrationId, final String endpointChannel)
    {
        final long correlationId = toDriverCommandBuffer.nextCorrelationId();
        final int length = DestinationMessageFlyweight.computeLength(endpointChannel.length());
        final int index = toDriverCommandBuffer.tryClaim(REMOVE_DESTINATION, length);
        if (index < 0)
        {
            throw new AeronException("failed to write remove 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 publicationRegistrationId  of the Publication.

View on GitHub (pinned to 6d60124e15)