{"record":{"id":"baa9cdaffd2606ba","repo":"aeron-io/aeron","slug":"failed-to-send-migrate-segments-request","errorCode":null,"errorMessage":"failed to send migrate segments request","messagePattern":"failed to send migrate segments request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2306,"sourceCode":"     * The source recording will be effectively truncated back to its start position after the migration.\n     *\n     * @param srcRecordingId source recording from which the segments will be migrated.\n     * @param dstRecordingId destination recording to which the segments will be attached.\n     * @return count of attached segment files.\n     */\n    public long migrateSegments(final long srcRecordingId, final long dstRecordingId)\n    {\n        lock.lock();\n        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.migrateSegments(srcRecordingId, dstRecordingId, lastCorrelationId, controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send migrate segments request\");\n            }\n\n            return pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    /**\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    {","sourceCodeStart":2288,"sourceCodeEnd":2324,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2288-L2324","documentation":"Thrown when the client fails to offer the migrateSegments request (move segments from a source recording to a target recording with matching channel/streams) to the archive control channel. The request never reached the archive, so no migration occurred.","triggerScenarios":"Calling AeronArchive.migrateSegments(srcRecordingId, dstRecordingId) when the control publication is not connected or the offer fails after retries due to backpressure.","commonSituations":"Archive down or restarting during a maintenance window; control-channel congestion; using a session whose archive has been recycled; incorrect control channel configuration in AeronArchive.Context.","solutions":["Check the archive is reachable and the control session is live; reconnect if necessary.","Retry migrateSegments with backoff after a transient offer failure.","Confirm srcRecordingId and dstRecordingId exist and have matching streams so the retry succeeds once delivered.","Review control channel configuration on both client and archive for mismatches."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure both recordings exist and channel is connected\nlong src = archive.getRecordingPosition(srcRecordingId); // throws if invalid\nif (!archive.controlResponsePoller().subscription().isConnected()) { reconnect(); }","typeGuard":null,"tryCatchPattern":"try {\n    archive.migrateSegments(srcRecordingId, dstRecordingId);\n} catch (ArchiveException e) {\n    backoffAndRetry(() -> archive.migrateSegments(srcRecordingId, dstRecordingId));\n}","preventionTips":["Confirm src/dst recordings share matching original channel and stream.","Run migrations outside heavy archive load windows.","Centralize archive session health checks."],"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"}