{"record":{"id":"8fabd623f0296976","repo":"apache/pulsar","slug":"invalid-value-s-for-the-position-allowed-values","errorCode":null,"errorMessage":"Invalid value %s for the position. Allowed values are [latest, earliest]","messagePattern":"Invalid value (.+?) for the position\\. Allowed values are \\[latest, earliest\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/ResetCursorData.java","lineNumber":65,"sourceCode":"    }\n\n    public ResetCursorData(long ledgerId, long entryId, boolean isExcluded, Map<String, String> properties) {\n        this.ledgerId = ledgerId;\n        this.entryId = entryId;\n        this.isExcluded = isExcluded;\n        this.properties = properties;\n    }\n\n    // Private constructor used only for json deserialization\n    private ResetCursorData(String position) {\n        if (\"latest\".equals(position)) {\n            this.ledgerId = Long.MAX_VALUE;\n            this.entryId = Long.MAX_VALUE;\n        } else if (\"earliest\".equals(position)) {\n            this.ledgerId = -1;\n            this.entryId = -1;\n        } else {\n            throw new IllegalArgumentException(\n                    String.format(\"Invalid value %s for the position. Allowed values are [latest, earliest]\",\n                            position));\n        }\n    }\n\n    public ResetCursorData(MessageId messageId) {\n        MessageIdAdv messageIdAdv = (MessageIdAdv) messageId;\n        this.ledgerId = messageIdAdv.getLedgerId();\n        this.entryId = messageIdAdv.getEntryId();\n        this.batchIndex = messageIdAdv.getBatchIndex();\n        this.partitionIndex = messageIdAdv.getPartitionIndex();\n        if (messageId instanceof TopicMessageId) {\n            throw new IllegalArgumentException(\"Not supported operation on partitioned-topic\");\n        }\n    }\n\n}\n","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ResetCursorData.java#L47-L83","documentation":"ResetCursorData's String constructor only accepts the exact literals \"latest\" and \"earliest\" as a position; any other string cannot be mapped to a message position and triggers this IllegalArgumentException. Use the MessageId constructor for arbitrary positions.","triggerScenarios":"Building ResetCursorData from user/CLI/API input where the position string is anything other than exactly \"latest\" or \"earliest\" (case differences like \"Latest\"/\"LATEST\", whitespace, or synonyms like \"beginning\"/\"end\").","commonSituations":"REST/admin tooling passing a user-supplied reset-position string through unvalidated; config files with mixed-case values; older code using \"beginning\"/\"end\" conventions instead of \"earliest\"/\"latest\".","solutions":["Normalize input with position.trim().toLowerCase() before constructing ResetCursorData","Map alternative synonyms (beginning->earliest, end->latest) before calling the constructor","For arbitrary positions use new ResetCursorData(MessageId) instead of the string form"],"exampleFix":"// before\nnew ResetCursorData(\"LATEST\"); // throws\n// after\nString p = input.trim().toLowerCase(Locale.ROOT);\nnew ResetCursorData(p); // \"latest\" or \"earliest\"","handlingStrategy":"validation","validationCode":"if (!\"latest\".equals(position) && !\"earliest\".equals(position)) {\n    throw new IllegalArgumentException(\"position must be 'latest' or 'earliest'\");\n}","typeGuard":"boolean isKnownPosition(String p) {\n    return \"latest\".equals(p) || \"earliest\".equals(p);\n}","tryCatchPattern":"try {\n    resetCursorData = new ResetCursorData(position);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid reset position '{}', defaulting to latest\", position);\n    resetCursorData = new ResetCursorData(\"latest\");\n}","preventionTips":["Normalize case/whitespace on user-supplied position strings before constructing","Prefer the ResetCursorData(MessageId) constructor for programmatic positions","Document the accepted literals [latest, earliest] where the position string is captured"],"tags":["java","pulsar-client","parsing","illegal-argument","cursor"],"backgroundTag":"invalid-enum-string","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}