{"record":{"id":"605bd954f1a90de8","repo":"t8y2/dbx","slug":"timestampms-is-required-when-position-is-timestamp","errorCode":null,"errorMessage":"timestampMs is required when position is timestamp","messagePattern":"timestampMs is required when position is timestamp","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java","lineNumber":1569,"sourceCode":"        try {\n            java.math.BigDecimal decimal = element.getAsBigDecimal();\n            if (decimal.signum() < 0 || decimal.stripTrailingZeros().scale() > 0) {\n                throw new IllegalArgumentException(name + \" must be a non-negative integer\");\n            }\n            return decimal.longValueExact();\n        } catch (ArithmeticException error) {\n            throw new IllegalArgumentException(name + \" is outside the supported integer range\", error);\n        }\n    }\n\n    static OffsetSpec offsetSpecForPosition(String position, Long timestampMs) {\n        String normalized = position == null ? \"latest\" : position.trim().toLowerCase(Locale.ROOT);\n        return switch (normalized) {\n            case \"earliest\" -> OffsetSpec.earliest();\n            case \"latest\", \"\" -> OffsetSpec.latest();\n            case \"timestamp\" -> {\n                if (timestampMs == null) {\n                    throw new IllegalArgumentException(\"timestampMs is required when position is timestamp\");\n                }\n                yield OffsetSpec.forTimestamp(timestampMs);\n            }\n            default -> throw new IllegalArgumentException(\"Unsupported reset position: \" + position);\n        };\n    }\n\n    // -----------------------------------------------------------------------\n    // Messages\n    // -----------------------------------------------------------------------\n\n    private static Object peekMessages(JsonObject params) throws Exception {\n        String topic = stringOrEmpty(params, \"topic\");\n        Integer partition = integerOrNull(params, \"partition\");\n        Long offset = longOrNull(params, \"offset\");\n        int count = validatedPeekCount(intOrDefault(params, \"count\", 10));\n        PeekStartPosition startPosition = peekStartPosition(params);\n        boolean explicitStartPosition = stringOrNull(params, \"startPosition\") != null;","sourceCodeStart":1551,"sourceCodeEnd":1587,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L1551-L1587","documentation":"offsetSpecForPosition maps a \"position\" string to a Kafka OffsetSpec. When position is \"timestamp\", a companion timestampMs value is mandatory; if it is null the agent throws IllegalArgumentException (KafkaAgent.java:1569).","triggerScenarios":"Calling the offset-listing/reset operation with position=\"timestamp\" (any casing/whitespace) but omitting timestampMs, or passing it as null.","commonSituations":"Config templates that set position but forget the timestamp parameter; timestamps stripped by an intermediate serializer that drops nulls.","solutions":["Provide timestampMs (epoch milliseconds as a number) whenever position is \"timestamp\"","Use position \"earliest\" or \"latest\" if a point-in-time lookup is not actually needed","Verify the params object still contains timestampMs after serialization"],"exampleFix":"// before\nparams.put(\"position\", \"timestamp\");\n// after\nparams.put(\"position\", \"timestamp\");\nparams.put(\"timestampMs\", 1712000000000L);","handlingStrategy":"validation","validationCode":"if (position === 'timestamp' && (timestampMs == null || typeof timestampMs !== 'number')) throw new Error('timestampMs required');","typeGuard":"function timestampReady(p){ return p.position !== 'timestamp' || (typeof p.timestampMs === 'number' && p.timestampMs >= 0); }","tryCatchPattern":"try { agent.execute(req); } catch (e) { if (String(e.message).includes('timestampMs is required')) { /* add timestampMs or change position */ } else throw e; }","preventionTips":["Always set timestampMs together with position='timestamp'","Fall back to 'latest' when no timestamp is available","Beware serializers that strip null/undefined fields"],"tags":["kafka","input-validation","missing-parameter"],"backgroundTag":"missing-required-parameter","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}