aeron-io/aeron · critical · AeronException

failed to write add publication command

Error message

failed to write add publication command

What it means

DriverProxy.addPublication() throws AeronException when toDriverCommandBuffer.tryClaim(ADD_PUBLICATION, length) returns a negative value, meaning the client-to-driver ring buffer had no space to write the command. This is an internal client failure: tryClaim is expected to retry internally (via ClientConductor's agent), so failure here usually indicates the driver is not consuming commands or the client conductor is misconfigured/closed.

Solutions

1. Verify the media driver is running and consuming commands (check driver logs, aeron directory).
2. Retry Aeron.addPublication() after the driver has recovered; recreate the Aeron client if the conductor was closed.
3. Check client concurrency: ensure addPublication is not called concurrently with Aeron.close() on the same instance.
4. Increase driver responsiveness or reduce burst of publication/subscription creation calls.

Example fix

// before
Publication pub = aeron.addPublication(channel, streamId); // throws if buffer full
// after
Publication pub;
try { pub = aeron.addPublication(channel, streamId); }
catch (AeronException e) { restartDriverAndReconnect(); pub = aeron.addPublication(channel, streamId); }

if (aeron.isClosed() || !driverIsAlive()) {
    throw new IllegalStateException("cannot addPublication: client closed or driver not running");
}

null

try {
    Publication pub = aeron.addPublication(channel, streamId);
} catch (AeronException e) {
    if (aeron.isClosed()) { reconnectNewClient(); } else { retryWithBackoff(); }
}

When it happens

Trigger: Calling Aeron.addPublication() while the client-to-driver command buffer is full and cannot be claimed — typically when the media driver is not running/not consuming, the client conductor is being closed concurrently, or the claim retry loop is skipped.

Common situations: Driver process crashed or was killed while the client still holds the Aeron instance; Aeron client created with a wrong directory or driver-embedded mode mismatch; calling addPublication during client shutdown; extremely slow driver under load so the buffer stays full.

Related errors

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

Appendix: source

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

    {
        return toDriverCommandBuffer.consumerHeartbeatTime();
    }

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

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

        toDriverCommandBuffer.commit(index);

        return correlationId;
    }

    /**
     * Instruct the driver to add a non-concurrent, i.e. exclusive, publication.
     *
     * @param channel  uri in string format.

View on GitHub (pinned to 6d60124e15)