{"record":{"id":"aafb14d9b9720d7a","repo":"aeron-io/aeron","slug":"invalid-recordingid","errorCode":null,"errorMessage":"invalid recordingId ","messagePattern":"invalid recordingId ","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/PersistentSubscription.java","lineNumber":1717,"sourceCode":"\n            if (Aeron.NULL_VALUE == replayStreamId)\n            {\n                throw new ConfigurationException(\"replayStreamId must be set\");\n            }\n\n            if (null == aeronArchiveContext)\n            {\n                throw new ConfigurationException(\"aeronArchiveContext must be set\");\n            }\n\n            if (null == listener)\n            {\n                listener = new NoOpPersistentSubscriptionListener();\n            }\n\n            if (0 > recordingId)\n            {\n                throw new ConfigurationException(\"invalid recordingId \" + recordingId);\n            }\n\n            if (FROM_LIVE > startPosition)\n            {\n                throw new ConfigurationException(\"invalid startPosition \" + startPosition);\n            }\n\n            final ChannelUri replayChannelUri = ChannelUri.parse(replayChannel);\n\n            if (replayChannelUri.hasControlModeResponse())\n            {\n                final String controlRequestChannel = aeronArchiveContext.controlRequestChannel();\n                if (null != controlRequestChannel &&\n                    !replayChannelUri.isIpc() == ChannelUri.parse(controlRequestChannel).isIpc()\n                )\n                {\n                    throw new ConfigurationException(\n                        \"Channel media type mismatch. \" +","sourceCodeStart":1699,"sourceCodeEnd":1735,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/PersistentSubscription.java#L1699-L1735","documentation":"conclude() validates that recordingId is non-negative (0 is a valid recording id). A negative value means the recording id was never assigned (left at Aeron.NULL_VALUE = -1) or was corrupted, so the archive would be asked to replay a nonexistent recording. A ConfigurationException naming the offending id is thrown.","triggerScenarios":"conclude() called while recordingId < 0, typically still at the Aeron.NULL_VALUE default because no recordingId(...) setter was invoked or the caller passed a sentinel/'unknown' value.","commonSituations":"Starting a persistent subscription before the recording has actually started (recordingId not yet known); hardcoding -1 as 'auto'; a failed listRecording/RecordingDescriptorPoller lookup returning a sentinel that is forwarded unchanged.","solutions":["Obtain a valid recordingId (>= 0) from the archive (e.g. via AeronArchive.startRecording or RecordingDescriptorPoller) and set it before conclude().","Guard your code: only construct the persistent subscription after recordingId is known.","If you intended to follow a live recording from its start, ensure recording started successfully and its id was captured in the RecordingSignal/started event."],"exampleFix":"// before\nctx.recordingId(Aeron.NULL_VALUE); // or never set\nctx.conclude(); // throws: invalid recordingId -1\n\n// after\nfinal long recordingId = archive.startRecording(\n    \"aeron:udp?endpoint=localhost:10000\", 5, SourceLocation.LOCAL, true);\nctx.recordingId(recordingId);\nctx.conclude();","handlingStrategy":"validation","validationCode":"if (recordingId < 0) {\n    throw new IllegalArgumentException(\"recordingId must be >= 0, got \" + recordingId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ctx.conclude();\n} catch (ConfigurationException e) {\n    // recordingId not yet known: wait for RecordingSignal/started event\n}","preventionTips":["Only construct the persistent subscription after receiving a valid recordingId from startRecording or a descriptor poller.","Treat Aeron.NULL_VALUE as 'unknown' and never pass it through to the subscription."],"tags":["aeron-archive","configuration","invalid-value"],"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-19T12:17:13.211Z"}