{"record":{"id":"2c0dab90148e27b7","repo":"aeron-io/aeron","slug":"failed-to-write-add-publication-command","errorCode":null,"errorMessage":"failed to write add publication command","messagePattern":"failed to write add publication command","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"critical","filePath":"aeron-client/src/main/java/io/aeron/DriverProxy.java","lineNumber":86,"sourceCode":"    {\n        return toDriverCommandBuffer.consumerHeartbeatTime();\n    }\n\n    /**\n     * Instruct the driver to add a concurrent publication.\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 addPublication(final String channel, final int streamId)\n    {\n        final long correlationId = toDriverCommandBuffer.nextCorrelationId();\n        final int length = PublicationMessageFlyweight.computeLength(channel.length());\n        final int index = toDriverCommandBuffer.tryClaim(ADD_PUBLICATION, length);\n        if (index < 0)\n        {\n            throw new AeronException(\"failed to write add publication command\");\n        }\n\n        publicationMessageFlyweight\n            .wrap(toDriverCommandBuffer.buffer(), index)\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 add a non-concurrent, i.e. exclusive, publication.\n     *\n     * @param channel  uri in string format.","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DriverProxy.java#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the media driver is running and consuming commands (check driver logs, aeron directory).","Retry Aeron.addPublication() after the driver has recovered; recreate the Aeron client if the conductor was closed.","Check client concurrency: ensure addPublication is not called concurrently with Aeron.close() on the same instance.","Increase driver responsiveness or reduce burst of publication/subscription creation calls."],"exampleFix":"// before\nPublication pub = aeron.addPublication(channel, streamId); // throws if buffer full\n// after\nPublication pub;\ntry { pub = aeron.addPublication(channel, streamId); }\ncatch (AeronException e) { restartDriverAndReconnect(); pub = aeron.addPublication(channel, streamId); }","handlingStrategy":"try-catch","validationCode":"if (aeron.isClosed() || !driverIsAlive()) {\n    throw new IllegalStateException(\"cannot addPublication: client closed or driver not running\");\n}","typeGuard":"null","tryCatchPattern":"try {\n    Publication pub = aeron.addPublication(channel, streamId);\n} catch (AeronException e) {\n    if (aeron.isClosed()) { reconnectNewClient(); } else { retryWithBackoff(); }\n}","preventionTips":["Monitor driver liveness (driver heartbeats / process supervision) before creating publications.","Avoid bursts of publication creation; pool and reuse Publication instances.","Ensure Aeron.close() is not racing with addPublication calls."],"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"}