{"record":{"id":"b0c9a58306111b19","repo":"aeron-io/aeron","slug":"timestamp-offset-must-be-a-valid-integer-or-the-reserved","errorCode":null,"errorMessage":"timestamp offset must be a valid integer or the 'reserved' keyword","messagePattern":"timestamp offset must be a valid integer or the 'reserved' keyword","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java","lineNumber":321,"sourceCode":"    {\n        final String offsetStr = channelUri.get(timestampOffsetParamName);\n        if (null == offsetStr)\n        {\n            return Aeron.NULL_VALUE;\n        }\n        else if (RESERVED_OFFSET.equals(offsetStr))\n        {\n            return RESERVED_VALUE_MESSAGE_OFFSET;\n        }\n        else\n        {\n            try\n            {\n                return Integer.parseInt(offsetStr);\n            }\n            catch (final NumberFormatException ex)\n            {\n                throw new IllegalArgumentException(\n                    \"timestamp offset must be a valid integer or the 'reserved' keyword\", ex);\n            }\n        }\n    }\n\n    private static Long parseOptionalLong(final ChannelUri channelUri, final String paramName)\n    {\n        final String longAsString = channelUri.get(paramName);\n        if (null == longAsString)\n        {\n            return null;\n        }\n\n        try\n        {\n            return Long.valueOf(longAsString);\n        }\n        catch (final NumberFormatException ex)","sourceCodeStart":303,"sourceCodeEnd":339,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java#L303-L339","documentation":"Thrown when a channel URI's timestamp offset parameter (e.g. sesion-name-tagged channels' 'smdc-timestamp-offset' style params) is neither the keyword 'reserved' nor a parseable integer. Aeron requires an int offset or 'reserved'.","triggerScenarios":"Setting a timestamp offset parameter to a non-numeric string such as 'auto' or '5x', or an empty value.","commonSituations":"Copy-pasted config with wrong units or placeholder text, template variables left unsubstituted, confusion between offset and size parameters.","solutions":["Set the parameter to a valid integer (byte offset) or the literal string 'reserved'","Remove the parameter entirely if no timestamp offset is wanted","Check for unsubstituted template variables in the channel URI"],"exampleFix":"// before\n\"aeron:udp?endpoint=...|ts-offset=auto\"\n// after\n\"aeron:udp?endpoint=...|ts-offset=reserved\"","handlingStrategy":"validation","validationCode":"String v = uri.getParam(\"ts-offset\"); if (v != null && !v.equals(\"reserved\") && !v.matches(\"-?\\\\d+\")) throw new IllegalArgumentException(\"ts-offset must be int or 'reserved'\");","typeGuard":"static boolean isValidTimestampOffset(String v) { return v == null || v.equals(\"reserved\") || v.matches(\"-?\\\\d+\"); }","tryCatchPattern":"try { parseTimestampOffset(uri); } catch (IllegalArgumentException e) { log.warn(\"bad ts-offset in {}: {}\", uri, e.getMessage()); }","preventionTips":["Use 'reserved' keyword instead of hand-computed offsets","Avoid template placeholders in numeric parameters","Document accepted values for timestamp offset params in your config schema"],"tags":["aeron","channel-uri","invalid-format"],"backgroundTag":"invalid-argument-format","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"}