{"record":{"id":"27f130b9752dc1d9","repo":"aeron-io/aeron","slug":"failed-to-write-add-exclusive-publication-command","errorCode":null,"errorMessage":"failed to write add exclusive publication command","messagePattern":"failed to write add exclusive publication command","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"critical","filePath":"aeron-client/src/main/java/io/aeron/DriverProxy.java","lineNumber":115,"sourceCode":"\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.\n     * @param streamId within the channel.\n     * @return the correlation id for the command.\n     */\n    public long addExclusivePublication(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_EXCLUSIVE_PUBLICATION, length);\n        if (index < 0)\n        {\n            throw new AeronException(\"failed to write add exclusive 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 remove a publication by its registration id.\n     *\n     * @param registrationId for the publication to be removed.","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DriverProxy.java#L97-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the media driver is alive and its conductor thread is consuming client commands.","Rate-limit or batch exclusive publication creation; back off and retry when the driver is overloaded.","If the client conductor is closed, create a new Aeron client instead of retrying on the old one."],"exampleFix":"// before\nExclusivePublication pub = aeron.addExclusivePublication(channel, streamId);\n// after\nExclusivePublication pub = retryOnFailure(() -> aeron.addExclusivePublication(channel, streamId), 3, TimeUnit.SECONDS);","handlingStrategy":"try-catch","validationCode":"if (aeron.isClosed() || !driverIsAlive()) {\n    throw new IllegalStateException(\"cannot addExclusivePublication: driver unavailable\");\n}","typeGuard":"null","tryCatchPattern":"try {\n    ExclusivePublication pub = aeron.addExclusivePublication(channel, streamId);\n} catch (AeronException e) {\n    log.error(\"driver command buffer full; driver likely down\", e);\n    scheduleReconnect();\n}","preventionTips":["Rate-limit exclusive publication creation; each one allocates dedicated driver resources.","Keep the driver conductor unblocked (no long user callbacks).","Use shared publications unless exclusivity is strictly required."],"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"}