aeron-io/aeron · critical · AeronException

failed to write add subscription command

Error message

failed to write add subscription command

What it means

DriverProxy.addSubscription() throws AeronException when tryClaim(ADD_SUBSCRIPTION, length) fails, i.e. the client-to-driver command buffer has no room for the subscription request. Aeron expects its retry/backoff within the client agent to make claims succeed; a negative return indicates the driver stopped consuming or the client is shutting down.

Solutions

1. Verify the driver is up and using the same aeron.dir as the client.
2. Stagger subscription creation rather than issuing all requests in one burst.
3. Inspect driver conductor callbacks (availableImageHandler etc.) for blocking work.

Example fix

// before
Subscription sub = aeron.addSubscription(channel, streamId);
// after
Subscription sub = awaitDriverThen(() -> aeron.addSubscription(channel, streamId));

if (!Files.exists(Paths.get(aeronDir, "aeron-driver.pid")) && !embeddedDriver) {
    throw new IllegalStateException("media driver is not running");
}

null

try {
    Subscription sub = aeron.addSubscription(channel, streamId);
} catch (AeronException e) {
    retryWithBackoff(() -> aeron.addSubscription(channel, streamId));
}

When it happens

Trigger: Calling Aeron.addSubscription() (directly or via Aeron.connect flows) while the to-driver ring buffer is saturated — driver not running, driver thread blocked, or a burst of subscription commands.

Common situations: Service startup creating many subscriptions before the driver finishes initialization; embedded driver started in a different directory than the client expects; driver conductor blocked by a user callback.

Related errors

• failed to write add publication command
• failed to write add exclusive publication command
• failed to write remove publication 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/d17ed1898da89efe. Report an issue: GitHub.

Appendix: source

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

        return correlationId;
    }

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

        subscriptionMessageFlyweight
            .wrap(toDriverCommandBuffer.buffer(), index)
            .registrationCorrelationId(registrationId)
            .streamId(streamId)
            .channel(channel)
            .clientId(clientId)
            .correlationId(correlationId);

        toDriverCommandBuffer.commit(index);

        return correlationId;
    }

    /**
     * Instruct the driver to remove a subscription by its registration id.
     *

View on GitHub (pinned to 6d60124e15)