aeron-io/aeron · error · AeronException

failed to write add rcv destination command

Error message

failed to write add rcv destination command

What it means

DriverProxy.addRcvDestination claims space in the toDriverCommandBuffer to write an ADD_RCV_DESTINATION command for a ManualMdc/Udp multicast-style receive destination. tryClaim returned negative because the ring buffer lacked capacity for the message length, so the command could not be published and AeronException is thrown. It signals the client cannot enqueue commands because the driver is not draining them.

Solutions

1. Verify the media driver process/agent is running and consuming commands
2. Retry addRcvDestination with backoff; the claim failure is transient when the driver is merely slow
3. Rate-limit destination reconfiguration calls so the ring buffer does not fill
4. For embedded drivers, check driver agent thread is not blocked and increase command queue capacity if needed
5. Inspect client error log (ErrorHandler) for driver liveness signals before retrying

Example fix

// before
subscription.addRcvDestination(channel);
// after
try {
    subscription.addRcvDestination(channel);
} catch (AeronException e) {
    if (!driverService.isRunning()) {
        throw new IllegalStateException("media driver not consuming commands", e);
    }
    Thread.sleep(50);
    subscription.addRcvDestination(channel); // retry once buffer has drained
}

if (!aeron.context().isDriverActive()) {
    throw new IllegalStateException("driver inactive; addRcvDestination would fail");
}

try {
    subscription.addRcvDestination(channel);
} catch (AeronException e) {
    if (!e.getMessage().startsWith("failed to write")) throw e;
    // backoff then retry once; treat repeated failure as driver loss
}

When it happens

Trigger: Calling Subscription.addRcvDestination via DriverProxy when the client-driver command ring is full: driver process dead, driver stalled (GC, breakpoint), or a burst of add/remove destination commands exceeding drain rate.

Common situations: Media driver crashed mid-session while client continued reconfiguring MDC subscriptions; unit tests issuing many addRcvDestination calls in a loop; embedded driver sharing a saturated thread with the consuming agent.

Related errors

• failed to write remove rcv destination command
• failed to write add counter command
• failed to write remove counter command
• failed to write reject image command
• failed to write next session id command

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

Appendix: source

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

        return correlationId;
    }

    /**
     * Add a destination to the receive channel endpoint of an existing MDS Subscription.
     *
     * @param registrationId  of the Subscription.
     * @param endpointChannel for the destination.
     * @return the correlation id for the command.
     */
    public long addRcvDestination(final long registrationId, final String endpointChannel)
    {
        final long correlationId = toDriverCommandBuffer.nextCorrelationId();
        final int length = DestinationMessageFlyweight.computeLength(endpointChannel.length());
        final int index = toDriverCommandBuffer.tryClaim(ADD_RCV_DESTINATION, length);
        if (index < 0)
        {
            throw new AeronException("failed to write add rcv 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 receive channel endpoint of an existing MDS Subscription.
     *
     * @param registrationId  of the Subscription.

View on GitHub (pinned to 6d60124e15)