{"record":{"id":"c7c2b9df1677c455","repo":"aeron-io/aeron","slug":"failed-to-send-tagged-replicate-request","errorCode":null,"errorMessage":"failed to send tagged replicate request","messagePattern":"failed to send tagged replicate request","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":1954,"sourceCode":"        try\n        {\n            ensureConnected();\n            ensureNotReentrant();\n\n            lastCorrelationId = aeron.nextCorrelationId();\n\n            if (!archiveProxy.taggedReplicate(\n                srcRecordingId,\n                dstRecordingId,\n                channelTagId,\n                subscriptionTagId,\n                srcControlStreamId,\n                srcControlChannel,\n                liveDestination,\n                lastCorrelationId,\n                controlSessionId))\n            {\n                throw new ArchiveException(\"failed to send tagged replicate request\");\n            }\n\n            return pollForResponse(lastCorrelationId);\n        }\n        finally\n        {\n            lock.unlock();\n        }\n    }\n\n    /**\n     * Replicate a recording from a source archive to a destination which can be considered a backup for a primary\n     * archive. The source recording will be replayed via the provided replay channel and use the original stream id.\n     * If the destination recording id is {@link io.aeron.Aeron#NULL_VALUE} then a new destination recording is created,\n     * otherwise the provided destination recording id will be extended. The details of the source recording\n     * descriptor will be replicated. The subscription used in the archive will be tagged with the provided tags.\n     * <p>\n     * For a source recording that is still active the replay can merge with the live stream and then follow it","sourceCodeStart":1936,"sourceCodeEnd":1972,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L1936-L1972","documentation":"Thrown when a tagged replicate request could not be offered to the archive control publication. ArchiveProxy.taggedReplicate returned false after retries, so the archive never received the replication request carrying the replay/subscription tags. This is a transport-level failure on the control channel.","triggerScenarios":"Calling AeronArchive.taggedReplicate(srcRecordingId, dstRecordingId, channelTagId, subscriptionTagId, srcControlStreamId, srcControlChannel, liveDestination) while the control publication is closed, disconnected, or persistently back-pressured.","commonSituations":"Control session expired during a long catalog operation; destination archive under heavy load so the exclusive publication cannot accept offers; tags configured but the underlying session was already closed by the archive.","solutions":["Reconnect the archive session (AeronArchive.connect) and retry taggedReplicate.","Check the archive's load and control channel back-pressure counters; throttle concurrent client operations.","Verify srcControlChannel connectivity from the destination archive host before replicating.","Review Aeron error log for publication-level errors preceding the failure.","Consider a dedicated control session for replication-heavy workloads to avoid contention with other clients."],"exampleFix":"// before\narchive.taggedReplicate(srcRecordingId, dstRecordingId, channelTag, subscriptionTag, srcControlStreamId, srcControlChannel, null);\n// after\ntry {\n    archive.taggedReplicate(srcRecordingId, dstRecordingId, channelTag, subscriptionTag, srcControlStreamId, srcControlChannel, null);\n} catch (ArchiveException e) {\n    if (e.message().contains(\"failed to send\")) {\n        archive = AeronArchive.connect(ctx);\n        archive.taggedReplicate(srcRecordingId, dstRecordingId, channelTag, subscriptionTag, srcControlStreamId, srcControlChannel, null);\n    } else {\n        throw e;\n    }\n}","handlingStrategy":"try-catch","validationCode":"if (archive == null || archive.context().isClosed()) { archive = AeronArchive.connect(ctx); }","typeGuard":"static boolean isSendFailure(ArchiveException e) { return e.getMessage() != null && e.getMessage().contains(\"failed to send\"); }","tryCatchPattern":"try { archive.taggedReplicate(...); } catch (ArchiveException e) { if (isSendFailure(e)) { archive = AeronArchive.connect(ctx); archive.taggedReplicate(...); } else { throw e; } }","preventionTips":["Throttle concurrent archive operations to prevent control-channel back-pressure.","Keep the session warm if tagged replication is issued intermittently.","Verify source archive reachability before replication.","Watch Aeron error logs for early publication-close signals."],"tags":["aeron-archive","replication","control-session","ipc-offer-failed"],"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"}