{"record":{"id":"0a6d92dd80190946","repo":"apache/pulsar","slug":"start-message-id-must-be-latest-or-earliest","errorCode":null,"errorMessage":"--start-message-id must be 'latest' or 'earliest'; the '<ledgerId>:<entryId>' form is not supported by this version of pulsar-client.","messagePattern":"--start-message-id must be 'latest' or 'earliest'; the '<ledgerId>:<entryId>' form is not supported by this version of pulsar-client\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdRead.java","lineNumber":128,"sourceCode":"    private boolean printMetadata = false;\n\n    public CmdRead() {\n        // Do nothing\n        super();\n    }\n\n    /**\n     * Run the read command.\n     *\n     * @return 0 for success, < 0 otherwise\n     */\n    public int run() throws PulsarClientException, IOException {\n        if (this.numMessagesToRead < 0) {\n            throw (new IllegalArgumentException(\"Number of messages should be zero or positive.\"));\n        }\n        if (!START_LATEST.equals(startMessageId) && !START_EARLIEST.equals(startMessageId)) {\n            throw new IllegalArgumentException(\"--start-message-id must be 'latest' or 'earliest'; the \"\n                    + \"'<ledgerId>:<entryId>' form is not supported by this version of pulsar-client.\");\n        }\n\n        if (this.serviceURL.startsWith(\"ws\")) {\n            return readFromWebSocket(topic);\n        } else {\n            return read(topic);\n        }\n    }\n\n    private int read(String topic) {\n        int numMessagesRead = 0;\n        int returnCode = 0;\n\n        final Schema<?> schema;\n        if (\"auto_consume\".equals(schemaType)) {\n            schema = Schema.autoConsume();\n        } else if (\"bytes\".equals(schemaType)) {\n            schema = Schema.bytes();","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdRead.java#L110-L146","documentation":"This V5-based pulsar-client CLI does not support numeric MessageId (ledgerId:entryId) start positions for the read command. Only the symbolic values 'latest' and 'earliest' are accepted; anything else throws IllegalArgumentException and the command exits.","triggerScenarios":"Running `pulsar-client read <topic> --start-message-id '12:3'` or any '<ledgerId>:<entryId>' string instead of 'latest'/'earliest'.","commonSituations":"Porting scripts written against the full pulsar-client where numeric message IDs were supported; users copying a MessageId from broker logs or admin output; automation that formats the position from a previous read.","solutions":["Use --start-message-id latest or --start-message-id earliest.","If you need an exact position, use the full Java client Reader with MessageId, or the admin/reader APIs in a non-V5 client.","Strip any numeric ID formatting from your script and map it to 'latest'/'earliest' semantics."],"exampleFix":"// before\npulsar-client read my-topic --start-message-id 1287:43\n// after\npulsar-client read my-topic --start-message-id latest","handlingStrategy":"validation","validationCode":"// bash: only symbolic positions allowed\ncase \"$START_ID\" in latest|earliest) ;; *) echo \"use latest or earliest, got: $START_ID\"; exit 1;; esac","typeGuard":"function isValidStartMessageId(v) { return v === 'latest' || v === 'earliest'; }","tryCatchPattern":"try { readCmd(startId); } catch (IllegalArgumentException e) { if (e.getMessage().includes(\"--start-message-id\")) { /* fall back to 'latest' */ } else throw e; }","preventionTips":["Only pass latest/earliest for --start-message-id on this CLI.","Don't port ledgerId:entryId positions from the full client into this tool.","Map numeric positions to nearest symbolic semantics in scripts."],"tags":["cli","unsupported-feature","message-id","pulsar-client"],"backgroundTag":"unsupported-option-value","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}