aeron-io/aeron · critical · AeronException

failed to write add exclusive publication command

Error message

failed to write add exclusive publication command

What it means

DriverProxy.addExclusivePublication() throws AeronException when tryClaim(ADD_EXCLUSIVE_PUBLICATION, length) fails to reserve space in the client-to-driver command buffer. As with addPublication, this means the driver is not draining the command buffer fast enough or the client conductor is shutting down, so the exclusive publication request could not be written.

Solutions

1. Confirm the media driver is alive and its conductor thread is consuming client commands.
2. Rate-limit or batch exclusive publication creation; back off and retry when the driver is overloaded.
3. If the client conductor is closed, create a new Aeron client instead of retrying on the old one.

Example fix

// before
ExclusivePublication pub = aeron.addExclusivePublication(channel, streamId);
// after
ExclusivePublication pub = retryOnFailure(() -> aeron.addExclusivePublication(channel, streamId), 3, TimeUnit.SECONDS);

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

null

try {
    ExclusivePublication pub = aeron.addExclusivePublication(channel, streamId);
} catch (AeronException e) {
    log.error("driver command buffer full; driver likely down", e);
    scheduleReconnect();
}

When it happens

Trigger: Calling Aeron.addExclusivePublication() when the to-driver ring buffer is full: driver dead or paused, conductor closing, or a burst of publication-creation commands exceeding driver consumption rate.

Common situations: Creating many exclusive publications in a tight loop against a slow or stopped driver; dedicated-mode driver thread blocked; client and driver in different processes and the driver container was terminated.

Related errors

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

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

Appendix: source

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

        return correlationId;
    }

    /**
     * Instruct the driver to add a non-concurrent, i.e. exclusive, publication.
     *
     * @param channel  uri in string format.
     * @param streamId within the channel.
     * @return the correlation id for the command.
     */
    public long addExclusivePublication(final String channel, final int streamId)
    {
        final long correlationId = toDriverCommandBuffer.nextCorrelationId();
        final int length = PublicationMessageFlyweight.computeLength(channel.length());
        final int index = toDriverCommandBuffer.tryClaim(ADD_EXCLUSIVE_PUBLICATION, length);
        if (index < 0)
        {
            throw new AeronException("failed to write add exclusive publication command");
        }

        publicationMessageFlyweight
            .wrap(toDriverCommandBuffer.buffer(), index)
            .streamId(streamId)
            .channel(channel)
            .clientId(clientId)
            .correlationId(correlationId);

        toDriverCommandBuffer.commit(index);

        return correlationId;
    }

    /**
     * Instruct the driver to remove a publication by its registration id.
     *
     * @param registrationId for the publication to be removed.

View on GitHub (pinned to 6d60124e15)