{"record":{"id":"36edd9a5fa396f84","repo":"aeron-io/aeron","slug":"ipc-merging-is-not-supported","errorCode":null,"errorMessage":"IPC merging is not supported","messagePattern":"IPC merging is not supported","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java","lineNumber":128,"sourceCode":"     * @param mergeProgressTimeoutMs to use for progress checks.\n     */\n    public ReplayMerge(\n        final Subscription subscription,\n        final AeronArchive archive,\n        final String replayChannel,\n        final String replayDestination,\n        final String liveDestination,\n        final long recordingId,\n        final long startPosition,\n        final EpochClock epochClock,\n        final long mergeProgressTimeoutMs)\n    {\n        if (subscription.channel().startsWith(IPC_CHANNEL) ||\n            replayChannel.startsWith(IPC_CHANNEL) ||\n            replayDestination.startsWith(IPC_CHANNEL) ||\n            liveDestination.startsWith(IPC_CHANNEL))\n        {\n            throw new IllegalArgumentException(\"IPC merging is not supported\");\n        }\n\n        if (!subscription.channel().contains(\"control-mode=manual\"))\n        {\n            throw new IllegalArgumentException(\n                \"Subscription URI must have 'control-mode=manual' uri=\" + subscription.channel());\n        }\n\n        this.archive = archive;\n        this.subscription = subscription;\n        this.epochClock = epochClock;\n        this.replayDestination = replayDestination;\n        this.liveDestination = liveDestination;\n        this.recordingId = recordingId;\n        this.startPosition = startPosition;\n        this.mergeProgressTimeoutMs = mergeProgressTimeoutMs;\n\n        replayChannelUri = ChannelUri.parse(replayChannel);","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java#L110-L146","documentation":"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'.","triggerScenarios":"Creating a ReplayMerge where subscription.channel(), replayChannel, replayDestination, or liveDestination starts with 'aeron:ipc'.","commonSituations":"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.","solutions":["Use a UDP channel, e.g. 'aeron:udp?endpoint=host:port', for the subscription","Set replayDestination and liveDestination to UDP URIs, e.g. 'aeron:udp?endpoint=localhost:0'","Switch replayChannel to a UDP URI","If IPC-only delivery is acceptable, use plain ReplayParams/ArchiveClient.replay instead of ReplayMerge"],"exampleFix":"// before\nSubscription sub = aeron.addSubscription(\"aeron:ipc\", 1001);\nnew ReplayMerge(archive, sub, \"aeron:ipc\", \"aeron:ipc\", \"aeron:ipc\", recordingId, 0);\n// after\nSubscription sub = aeron.addSubscription(\"aeron:udp?endpoint=0.0.0.0:2000|control-mode=manual\", 1001);\nnew ReplayMerge(archive, sub, \"aeron:udp?endpoint=localhost:2000\", \"aeron:udp?endpoint=localhost:0\", \"aeron:udp?endpoint=localhost:2001\", recordingId, 0);","handlingStrategy":"validation","validationCode":"if (sub.channel().startsWith(\"aeron:ipc\") || replayChannel.startsWith(\"aeron:ipc\")\n    || replayDest.startsWith(\"aeron:ipc\") || liveDest.startsWith(\"aeron:ipc\")) {\n    throw new IllegalArgumentException(\"ReplayMerge requires UDP channels\");\n}","typeGuard":null,"tryCatchPattern":"try { new ReplayMerge(archive, sub, replayChannel, replayDest, liveDest, recordingId, position); }\ncatch (IllegalArgumentException e) { if (e.getMessage().equals(\"IPC merging is not supported\")) { switchToUdpConfig(); } }","preventionTips":["Always use UDP URIs for ReplayMerge inputs","Validate channel URIs at config load time","Document that local IPC setups need UDP endpoints for merge"],"tags":["configuration","ipc","replay-merge","illegal-argument"],"backgroundTag":"invalid-argument-value","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"}