aeron-io/aeron · error · IllegalArgumentException

ReplicationParams.liveDestination and…

Error message

ReplicationParams.liveDestination and ReplicationParams.sessionId can not be specified together

What it means

An IllegalArgumentException thrown by ArchiveProxy.replicate when ReplicationParams specifies both a liveDestination (following a live stream) and a replicationSessionId (attaching to an existing replication session). These two options are mutually exclusive: one starts new live replication, the other joins an existing session.

Solutions

1. Remove ReplicationParams.replicationSessionId if you want a new live replication with a liveDestination
2. Remove ReplicationParams.liveDestination if you intend to join an existing replication session by id
3. Build a fresh ReplicationParams per replicate() call instead of reusing a mutated one

Example fix

// before
ReplicationParams params = new ReplicationParams()
    .liveDestination("aeron:udp?endpoint=src:40456")
    .replicationSessionId(sessionId); // conflict
// after
ReplicationParams params = new ReplicationParams()
    .liveDestination("aeron:udp?endpoint=src:40456"); // pick one option

if (params.liveDestination() != null && params.replicationSessionId() != Aeron.NULL_VALUE) {
    throw new IllegalStateException("liveDestination and replicationSessionId are mutually exclusive");
}

boolean replicationParamsConsistent(ReplicationParams p) {
    return !(p.liveDestination() != null && p.replicationSessionId() != Aeron.NULL_VALUE);
}

try { archive.replicate(srcRecordingId, params); } catch (IllegalArgumentException e) { sanitizeParamsAndRetry(); }

When it happens

Trigger: Calling archiveProxy.replicate (directly or via AeronArchive.replicate) with ReplicationParams where liveDestination() != null AND replicationSessionId() != Aeron.NULL_VALUE.

Common situations: Developer configures ReplicationParams for live-follow replication and also sets a session id copied from another replication; builder reuse across calls leaving stale fields set.

Related errors

• Archive.Context.replicationChannel must be set
• failed to send replay request
• failed to send replicate request
• failed to send stop replication request
• failed to send tagged replicate request

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/7c7f2ae347cf082b. Report an issue: GitHub.

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/ArchiveProxy.java:1252

     * @param srcControlChannel  remote control channel for the source archive to instruct the replay on.
     * @param srcControlStreamId remote control stream id for the source archive to instruct the replay on.
     * @param replicationParams  optional parameters to control the behaviour of the replication.
     * @param correlationId      for this request.
     * @param controlSessionId   for this request.
     * @return {@code true} if successfully offered otherwise {@code false}.
     * @see ReplicationParams
     */
    public boolean replicate(
        final long srcRecordingId,
        final int srcControlStreamId,
        final String srcControlChannel,
        final ReplicationParams replicationParams,
        final long correlationId,
        final long controlSessionId)
    {
        if (null != replicationParams.liveDestination() && Aeron.NULL_VALUE != replicationParams.replicationSessionId())
        {
            throw new IllegalArgumentException(
                "ReplicationParams.liveDestination and ReplicationParams.sessionId can not be specified together");
        }

        return replicate(
            srcRecordingId,
            replicationParams.dstRecordingId(),
            replicationParams.stopPosition(),
            replicationParams.channelTagId(),
            replicationParams.subscriptionTagId(),
            srcControlStreamId,
            srcControlChannel,
            replicationParams.liveDestination(),
            replicationParams.replicationChannel(),
            correlationId,
            controlSessionId,
            replicationParams.fileIoMaxLength(),
            replicationParams.replicationSessionId(),
            replicationParams.encodedCredentials(),

View on GitHub (pinned to 6d60124e15)