{"record":{"id":"cb6ab84a4f917248","repo":"aeron-io/aeron","slug":"failed-to-send-attach-segments-request","errorCode":null,"errorMessage":"failed to send attach segments request","messagePattern":"failed to send attach segments request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2267,"sourceCode":"     * they are being attached to.\n     *\n     * @param recordingId to which the operation applies.\n     * @return count of attached segment files.\n     * @see #detachSegments(long, long)\n     */\n    public long attachSegments(final long recordingId)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.attachSegments(recordingId, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send attach segments request\");\n            }\n\n            return pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    /**\n     * Migrate segments from a source recording and attach them to the beginning or end of a destination recording.\n     * <p>\n     * The source recording must match the destination recording for segment length, term length, mtu length,\n     * stream id. The source recording must join to the destination recording on a segment boundary and without gaps,\n     * i.e., the stop position and term id of one must match the start position and term id of the other.\n     * <p>\n     * The source recording must be stopped. The destination recording must be stopped if migrating segments","sourceCodeStart":2249,"sourceCodeEnd":2285,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2249-L2285","documentation":"Thrown when the client cannot offer the attachSegments request (re-attach previously detached segment files to a recording) to the archive control channel. ArchiveProxy.attachSegments returned false, meaning the request never reached the archive and the segments remain detached.","triggerScenarios":"Calling AeronArchive.attachSegments(recordingId) with a disconnected or backpressured control request publication.","commonSituations":"Archive agent not running or restarting; control channel misconfigured (wrong channel/streamId); buffer backpressure during heavy archive traffic; stale session after archive failover.","solutions":["Verify archive connectivity and reconnect the AeronArchive session if disconnected.","Retry attachSegments after a short delay; the offer failure is commonly transient.","Check controlRequestChannel and controlRequestStreamId against the archive's configured control channel.","Ensure segment files being attached are on storage visible to the archive before retrying."],"exampleFix":"// before\narchive.attachSegments(recordingId);\n// after\nif (archive == null || !archive.controlResponsePoller().subscription().isConnected()) {\n    archive = AeronArchive.connect(ctx);\n}\narchive.attachSegments(recordingId);","handlingStrategy":"retry","validationCode":"if (!archive.controlResponsePoller().subscription().isConnected()) {\n    archive = AeronArchive.connect(ctx);\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.attachSegments(recordingId);\n} catch (ArchiveException e) {\n    backoffAndRetry(() -> archive.attachSegments(recordingId));\n}","preventionTips":["Verify control channel configuration once at startup.","Ping the archive (e.g. archive.archiveProxy or a no-op request) before batch operations.","Keep segment files accessible to the archive before attaching."],"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"}