{"record":{"id":"ba79724bbcf4943e","repo":"aeron-io/aeron","slug":"failed-to-send-start-recording-request","errorCode":null,"errorMessage":"failed to send start recording request","messagePattern":"failed to send start recording request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":699,"sourceCode":"     * @param channel        to be recorded.\n     * @param streamId       to be recorded.\n     * @param sourceLocation of the publication to be recorded.\n     * @return the subscriptionId, i.e. {@link Subscription#registrationId()}, of the recording. This can be\n     * passed to {@link #stopRecording(long)}.\n     */\n    public long startRecording(final String channel, final int streamId, final SourceLocation sourceLocation)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.startRecording(channel, streamId, sourceLocation, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send start recording request\");\n            }\n\n            return pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    /**\n     * Start recording a channel and stream pairing.\n     * <p>\n     * Channels that include sessionId parameters are considered different from channels without sessionIds. If a\n     * publication matches both a sessionId specific channel recording and a non-sessionId specific recording,\n     * it will be recorded twice.\n     *\n     * @param channel        to be recorded.","sourceCodeStart":681,"sourceCodeEnd":717,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L681-L717","documentation":"startRecording sends a StartRecordingRequest to the archive via ArchiveProxy and then polls for the response. ArchiveProxy.startRecording returns false when the control request could not be offered/published on the control publication (e.g. publication back-pressure or not connected). The library throws ArchiveException in that case because the request never reached the archive.","triggerScenarios":"Calling AeronArchive.startRecording(channel, streamId, sourceLocation) when the control-request publication cannot accept the message — control session down, publication not connected, or send buffer full at offer time.","commonSituations":"Archive slow or control channel congested (offer retry limit exhausted); control session just established but publication not yet connected; archive under heavy load during many simultaneous recording requests.","solutions":["Retry startRecording after a short back-off; ensure the control session is connected first (ensureConnected/pollForResponse path)","Verify archive is running and control channel throughput is not saturated; reduce concurrent control requests","Catch ArchiveException and re-establish the archive connection via AeronArchive.connect() before retrying"],"exampleFix":"// before\narchive.startRecording(channel, streamId, SourceLocation.LOCAL); // throws on transient send failure\n// after\nwhile (!sendStarted) {\n    try { archive.startRecording(channel, streamId, SourceLocation.LOCAL); sendStarted = true; }\n    catch (ArchiveException ex) { Thread.sleep(100); }\n}","handlingStrategy":"retry","validationCode":"// pre-check control connectivity\nif (!archiveProxy.controlPublication().isConnected()) {\n    throw new IllegalStateException(\"archive control publication not connected\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.startRecording(channel, streamId, sourceLocation);\n} catch (ArchiveException ex) {\n    if (ex.getMessage().contains(\"failed to send\")) { retryWithBackoff(); }\n}","preventionTips":["Confirm control session is established before sending requests","Avoid bursting many control requests simultaneously","Monitor offer failures on the control publication"],"tags":["aeron-archive","ipc","backpressure"],"backgroundTag":"api-request-failed","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"}