{"record":{"id":"d17ed1898da89efe","repo":"aeron-io/aeron","slug":"failed-to-write-add-subscription-command","errorCode":null,"errorMessage":"failed to write add subscription command","messagePattern":"failed to write add subscription command","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"critical","filePath":"aeron-client/src/main/java/io/aeron/DriverProxy.java","lineNumber":173,"sourceCode":"        return correlationId;\n    }\n\n    /**\n     * Instruct the driver to add a subscription.\n     *\n     * @param channel  uri in string format.\n     * @param streamId within the channel.\n     * @return the correlation id for the command.\n     */\n    public long addSubscription(final String channel, final int streamId)\n    {\n        final long registrationId = Aeron.NULL_VALUE;\n        final long correlationId = toDriverCommandBuffer.nextCorrelationId();\n        final int length = SubscriptionMessageFlyweight.computeLength(channel.length());\n        final int index = toDriverCommandBuffer.tryClaim(ADD_SUBSCRIPTION, length);\n        if (index < 0)\n        {\n            throw new AeronException(\"failed to write add subscription command\");\n        }\n\n        subscriptionMessageFlyweight\n            .wrap(toDriverCommandBuffer.buffer(), index)\n            .registrationCorrelationId(registrationId)\n            .streamId(streamId)\n            .channel(channel)\n            .clientId(clientId)\n            .correlationId(correlationId);\n\n        toDriverCommandBuffer.commit(index);\n\n        return correlationId;\n    }\n\n    /**\n     * Instruct the driver to remove a subscription by its registration id.\n     *","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DriverProxy.java#L155-L191","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the driver is up and using the same aeron.dir as the client.","Stagger subscription creation rather than issuing all requests in one burst.","Inspect driver conductor callbacks (availableImageHandler etc.) for blocking work."],"exampleFix":"// before\nSubscription sub = aeron.addSubscription(channel, streamId);\n// after\nSubscription sub = awaitDriverThen(() -> aeron.addSubscription(channel, streamId));","handlingStrategy":"try-catch","validationCode":"if (!Files.exists(Paths.get(aeronDir, \"aeron-driver.pid\")) && !embeddedDriver) {\n    throw new IllegalStateException(\"media driver is not running\");\n}","typeGuard":"null","tryCatchPattern":"try {\n    Subscription sub = aeron.addSubscription(channel, streamId);\n} catch (AeronException e) {\n    retryWithBackoff(() -> aeron.addSubscription(channel, streamId));\n}","preventionTips":["Start the driver before client services that create subscriptions.","Confirm client and driver use the same aeron.dir.","Stagger subscription creation at startup instead of issuing all at once."],"tags":["aeron","driver-communication","ring-buffer-full","command-buffer"],"backgroundTag":"broken-pipe","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}