{"record":{"id":"7ae67fecd82ec01f","repo":"aeron-io/aeron","slug":"failed-to-send-purge-segments-request","errorCode":null,"errorMessage":"failed to send purge segments request","messagePattern":"failed to send purge segments request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2234,"sourceCode":"     * @param newStartPosition for the recording after the segments are detached.\n     * @return count of deleted segment files.\n     * @see #detachSegments(long, long)\n     * @see #deleteDetachedSegments(long)\n     * @see #segmentFileBasePosition(long, long, int, int)\n     */\n    public long purgeSegments(final long recordingId, final long newStartPosition)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.purgeSegments(recordingId, newStartPosition, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send purge segments request\");\n            }\n\n            return pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    /**\n     * Attach segments to the beginning of a recording to restore history that was previously detached.\n     * <p>\n     * Segment files must match the existing recording and join exactly to the start position of the recording\n     * they are being attached to.\n     *\n     * @param recordingId to which the operation applies.\n     * @return count of attached segment files.","sourceCodeStart":2216,"sourceCodeEnd":2252,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2216-L2252","documentation":"Thrown when the client fails to offer the purgeSegments request (truncate recording to a new start position and delete preceding segments) to the archive control channel. The ArchiveProxy send returned false so nothing was delivered to the archive; the recording is left unchanged.","triggerScenarios":"Calling AeronArchive.purgeSegments(recordingId, newStartPosition) when the control request publication is disconnected or backpressured so the offer retry loop gives up.","commonSituations":"Archive process down; network partition on the control channel; archive overloaded causing the control publication's terminal buffer to be full; stale AeronArchive session after archive restart.","solutions":["Confirm the archive is up and the control session is still connected, reconnecting if needed.","Retry the call with backoff, since offer failure is usually transient backpressure.","Validate newStartPosition is a valid segment-aligned position to avoid a later server-side error once connectivity is fixed.","Increase control publication retry/backoff parameters if purges regularly coincide with heavy archive load."],"exampleFix":"// before\narchive.purgeSegments(recordingId, newStartPosition);\n// after\ntry {\n    archive.purgeSegments(recordingId, newStartPosition);\n} catch (ArchiveException e) {\n    // offer failed - retry after backoff or reconnect\n    archive = AeronArchive.connect(ctx);\n    archive.purgeSegments(recordingId, newStartPosition);\n}","handlingStrategy":"retry","validationCode":"if (!archive.controlResponsePoller().subscription().isConnected()) {\n    archive = AeronArchive.connect(ctx);\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.purgeSegments(recordingId, newStartPosition);\n} catch (ArchiveException e) {\n    backoffAndRetry(() -> archive.purgeSegments(recordingId, newStartPosition));\n}","preventionTips":["Validate newStartPosition alignment before calling.","Retry transient send failures with exponential backoff.","Confirm archive capacity/load before bulk purge operations."],"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"}