{"record":{"id":"de1a848ece3bdb49","repo":"aeron-io/aeron","slug":"when-using-startreplay-with-a-response-channel-replayparams","errorCode":null,"errorMessage":"when using startReplay with a response channel, ReplayParams::subscriptionRegistrationId must be set","messagePattern":"when using startReplay with a response channel, ReplayParams::subscriptionRegistrationId must be set","errorType":"validation","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":4307,"sourceCode":"        }\n        catch (final Exception ex)\n        {\n            CloseHelper.close(replaySubscription);\n            throw ex;\n        }\n    }\n\n    private long startReplayViaResponseChannel(\n        final long recordingId,\n        final String replayChannel,\n        final int replayStreamId,\n        final ReplayParams replayParams)\n    {\n        lastCorrelationId = aeron.nextCorrelationId();\n\n        if (NULL_VALUE == replayParams.subscriptionRegistrationId())\n        {\n            throw new ArchiveException(\n                \"when using startReplay with a response channel, ReplayParams::subscriptionRegistrationId must be set\");\n        }\n\n        if (!archiveProxy.requestReplayToken(lastCorrelationId, controlSessionId, recordingId))\n        {\n            throw new ArchiveException(\"failed to send replay token request\");\n        }\n\n        final long replayToken = pollForResponse(lastCorrelationId);\n\n        replayParams.replayToken(replayToken);\n        final ChannelUriStringBuilder uriBuilder = new ChannelUriStringBuilder(context.controlRequestChannel())\n            .sessionId((Integer)null)\n            .responseCorrelationId(replayParams.subscriptionRegistrationId())\n            .termId((Integer)null).initialTermId((Integer)null).termOffset((Integer)null)\n            .termLength(context.controlTermBufferLength())\n            .spiesSimulateConnection(false);\n","sourceCodeStart":4289,"sourceCodeEnd":4325,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L4289-L4325","documentation":"Thrown by startReplay with a response channel when ReplayParams.subscriptionRegistrationId is NULL_VALUE. When the replay is driven over a response channel, the client must tell the archive which local subscription (by registration id) the replay should be attached to; without it the request is invalid and cannot proceed.","triggerScenarios":"Calling startReplay with a response-channel configuration while leaving ReplayParams.subscriptionRegistrationId unset (still Aeron NULL_VALUE).","commonSituations":"Developer adds a response channel but forgets to call ReplayParams.subscriptionRegistrationId(id) with the id returned by adding the replay subscription; copy-pasted replay params from a non-response-channel flow.","solutions":["Set ReplayParams.subscriptionRegistrationId to the registration id of the subscription added via Aeron.addSubscription for the replay channel","If not using a response channel, use the plain startReplay path without a response-channel configuration","Ensure the subscription is added before building ReplayParams so its registrationId is available"],"exampleFix":"// before\nReplayParams params = new ReplayParams();\n// subscriptionRegistrationId left NULL\n// after\nlong subRegId = aeron.addSubscription(replayChannel, replayStreamId).registrationId();\nReplayParams params = new ReplayParams();\nparams.subscriptionRegistrationId(subRegId);","handlingStrategy":"validation","validationCode":"if (replayParams.subscriptionRegistrationId() == Aeron.NULL_VALUE) {\n    throw new IllegalStateException(\"set ReplayParams.subscriptionRegistrationId before startReplay with a response channel\");\n}","typeGuard":"boolean replayParamsReady(ReplayParams p) { return p.subscriptionRegistrationId() != Aeron.NULL_VALUE; }","tryCatchPattern":null,"preventionTips":["Always set subscriptionRegistrationId when using a response channel","Add a pre-call assertion in helper wrappers around startReplay"],"tags":["aeron-archive","replay","missing-required-argument","replay-params"],"backgroundTag":"missing-required-argument","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}