aeron-io/aeron · error · IllegalArgumentException

IPC merging is not supported

Error message

IPC merging is not supported

What it means

ReplayMerge's constructor validates its configuration and rejects IPC channels for the subscription, replay channel, replay destination, or live destination. Replay merge requires media (UDP) transports to coordinate the replay and live endpoints, so IllegalArgumentException is thrown immediately when any URI starts with the IPC scheme 'aeron:ipc'.

Solutions

  1. Use a UDP channel, e.g. 'aeron:udp?endpoint=host:port', for the subscription
  2. Set replayDestination and liveDestination to UDP URIs, e.g. 'aeron:udp?endpoint=localhost:0'
  3. Switch replayChannel to a UDP URI
  4. If IPC-only delivery is acceptable, use plain ReplayParams/ArchiveClient.replay instead of ReplayMerge

Example fix

// before
Subscription sub = aeron.addSubscription("aeron:ipc", 1001);
new ReplayMerge(archive, sub, "aeron:ipc", "aeron:ipc", "aeron:ipc", recordingId, 0);
// after
Subscription sub = aeron.addSubscription("aeron:udp?endpoint=0.0.0.0:2000|control-mode=manual", 1001);
new ReplayMerge(archive, sub, "aeron:udp?endpoint=localhost:2000", "aeron:udp?endpoint=localhost:0", "aeron:udp?endpoint=localhost:2001", recordingId, 0);
Defensive patterns

Strategy: validation

Validate before calling

if (sub.channel().startsWith("aeron:ipc") || replayChannel.startsWith("aeron:ipc")
    || replayDest.startsWith("aeron:ipc") || liveDest.startsWith("aeron:ipc")) {
    throw new IllegalArgumentException("ReplayMerge requires UDP channels");
}

Try / catch

try { new ReplayMerge(archive, sub, replayChannel, replayDest, liveDest, recordingId, position); }
catch (IllegalArgumentException e) { if (e.getMessage().equals("IPC merging is not supported")) { switchToUdpConfig(); } }

Prevention

When it happens

Trigger: Creating a ReplayMerge where subscription.channel(), replayChannel, replayDestination, or liveDestination starts with 'aeron:ipc'.

Common situations: Developers testing locally default everything to IPC for simplicity, then try ReplayMerge; copy-pasting a subscription from a non-merge IPC setup into a ReplayMerge.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java:128

     * @param mergeProgressTimeoutMs to use for progress checks.
     */
    public ReplayMerge(
        final Subscription subscription,
        final AeronArchive archive,
        final String replayChannel,
        final String replayDestination,
        final String liveDestination,
        final long recordingId,
        final long startPosition,
        final EpochClock epochClock,
        final long mergeProgressTimeoutMs)
    {
        if (subscription.channel().startsWith(IPC_CHANNEL) ||
            replayChannel.startsWith(IPC_CHANNEL) ||
            replayDestination.startsWith(IPC_CHANNEL) ||
            liveDestination.startsWith(IPC_CHANNEL))
        {
            throw new IllegalArgumentException("IPC merging is not supported");
        }

        if (!subscription.channel().contains("control-mode=manual"))
        {
            throw new IllegalArgumentException(
                "Subscription URI must have 'control-mode=manual' uri=" + subscription.channel());
        }

        this.archive = archive;
        this.subscription = subscription;
        this.epochClock = epochClock;
        this.replayDestination = replayDestination;
        this.liveDestination = liveDestination;
        this.recordingId = recordingId;
        this.startPosition = startPosition;
        this.mergeProgressTimeoutMs = mergeProgressTimeoutMs;

        replayChannelUri = ChannelUri.parse(replayChannel);

View on GitHub (pinned to 6d60124e15)