{"record":{"id":"e6c3ce98557face4","repo":"aeron-io/aeron","slug":"failed-to-send-update-channel-request","errorCode":null,"errorMessage":"failed to send update channel request","messagePattern":"failed to send update channel request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2335,"sourceCode":"    /**\n     * Update the channel for a recording, i.e. replace original and stripped channel information in the catalog.\n     *\n     * @param recordingId the recording id to update.\n     * @param newChannel  to use in the catalogue.\n     */\n    public void updateChannel(final long recordingId, final String newChannel)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.updateChannel(recordingId, newChannel, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send update channel request\");\n            }\n\n            pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    private void checkDeadline(final long deadlineNs, final String errorMessage, final long correlationId)\n    {\n        if (deadlineNs - nanoClock.nanoTime() < 0)\n        {\n            throw new TimeoutException(\n                errorMessage + \" - correlationId=\" + correlationId + \" messageTimeout=\" +\n                SystemUtil.formatDuration(messageTimeoutNs));\n        }","sourceCodeStart":2317,"sourceCodeEnd":2353,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2317-L2353","documentation":"Thrown when the client cannot offer the updateChannel request (change the recording channel of a live recording) to the archive control channel. The ArchiveProxy send returned false, so the archive never received the request and the recording's channel is unchanged.","triggerScenarios":"Calling AeronArchive.updateChannel(recordingId, newChannel) while the control request publication is disconnected or persistently backpressured.","commonSituations":"Archive process down; network issues on the control channel; control buffer full under load; stale AeronArchive session reused after the archive restarted with a new session id.","solutions":["Verify control-channel connectivity and re-establish the AeronArchive session if it dropped.","Retry updateChannel after backoff; transient offer failures are common under load.","Validate newChannel URI is a valid replay/recording-capable channel before retrying.","Check archive logs to confirm the control listener is subscribed on the configured channel/stream."],"exampleFix":"// before\narchive.updateChannel(recordingId, newChannel);\n// after\ntry {\n    archive.updateChannel(recordingId, newChannel);\n} catch (ArchiveException e) {\n    archive = AeronArchive.connect(ctx); // refresh dead/stale session\n    archive.updateChannel(recordingId, newChannel);\n}","handlingStrategy":"try-catch","validationCode":"if (!archive.controlResponsePoller().subscription().isConnected()) {\n    archive = AeronArchive.connect(ctx);\n}\nAeronUri.parse(newChannel); // validate channel URI first","typeGuard":null,"tryCatchPattern":"try {\n    archive.updateChannel(recordingId, newChannel);\n} catch (ArchiveException e) {\n    archive = AeronArchive.connect(ctx);\n    archive.updateChannel(recordingId, newChannel);\n}","preventionTips":["Parse and validate the new channel URI before sending.","Reconnect stale sessions proactively.","Watch for archive restarts and re-establish sessions."],"tags":["aeron-archive","ipc-send-failure","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-19T12:17:13.211Z"}