{"record":{"id":"06d77919aadec858","repo":"aeron-io/aeron","slug":"invalid-startposition","errorCode":null,"errorMessage":"invalid startPosition ","messagePattern":"invalid startPosition ","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/PersistentSubscription.java","lineNumber":1722,"sourceCode":"\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. \" +\n                            \"When using `control-mode=response`, the `replayChannel` media type must match the media\" +\n                            \" type for the archive control channel.\"\n                    );\n                }\n            }","sourceCodeStart":1704,"sourceCodeEnd":1740,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/PersistentSubscription.java#L1704-L1740","documentation":"conclude() validates startPosition against the lowest legal sentinel: FROM_LIVE (-1) is the smallest allowed value, meaning 'join the live stream now'. Any smaller value (typically Aeron.NULL_VALUE = -2 when never set, or a corrupt negative) is invalid, so a ConfigurationException with the offending value is thrown.","triggerScenarios":"conclude() called with startPosition < FROM_LIVE, e.g. startPosition left at Aeron.NULL_VALUE (-2), or an application passing a negative position it computed itself.","commonSituations":"Forgetting to call startPosition(...) and assuming NULL_VALUE means 'from beginning'; confusing FROM_LIVE (-1) with NULL_VALUE (-2); passing a recordingPosition read before the recording began as a negative number.","solutions":["Set a valid startPosition: a non-negative byte position within the recording, or PersistentSubscription.FROM_LIVE to follow the live stream.","If you want to replay from the recording start, use position 0 (or the recording's startPosition from the descriptor).","Fix the calculation producing a negative position (e.g. clamp or validate before passing)."],"exampleFix":"// before\nctx.startPosition(Aeron.NULL_VALUE); // -2 < FROM_LIVE(-1)\nctx.conclude(); // throws: invalid startPosition -2\n\n// after\nctx.startPosition(0); // replay from recording start\n// or ctx.startPosition(PersistentSubscription.FROM_LIVE); // follow live","handlingStrategy":"validation","validationCode":"if (startPosition < PersistentSubscription.FROM_LIVE) {\n    throw new IllegalArgumentException(\"startPosition must be >= FROM_LIVE(-1), got \" + startPosition);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ctx.conclude();\n} catch (ConfigurationException e) {\n    // clamp to FROM_LIVE or 0 and retry\n}","preventionTips":["Use the named constants FROM_LIVE or 0 instead of hand-computed negative positions.","Do not confuse Aeron.NULL_VALUE (-2) with FROM_LIVE (-1)."],"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"}