{"record":{"id":"3c2dbfc82ac1c676","repo":"t8y2/dbx","slug":"offset-is-only-supported-when-startposition-is-off","errorCode":null,"errorMessage":"offset is only supported when startPosition is offset","messagePattern":"offset is only supported when startPosition is offset","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java","lineNumber":2134,"sourceCode":"    static void validatePeekRequest(\n        PeekStartPosition startPosition,\n        boolean explicitStartPosition,\n        Integer partition,\n        Long offset\n    ) {\n        if (partition != null && partition < 0) {\n            throw new IllegalArgumentException(\"partition must be non-negative\");\n        }\n        if (!explicitStartPosition) {\n            // Older clients used offset directly without a startPosition field.\n            if (offset != null && offset < 0) {\n                throw new IllegalArgumentException(\"offset must be non-negative\");\n            }\n            return;\n        }\n        if (startPosition != PeekStartPosition.OFFSET) {\n            if (offset != null) {\n                throw new IllegalArgumentException(\"offset is only supported when startPosition is offset\");\n            }\n            return;\n        }\n        if (offset == null) {\n            throw new IllegalArgumentException(\"offset is required when startPosition is offset\");\n        }\n        if (offset < 0) {\n            throw new IllegalArgumentException(\"offset must be non-negative when startPosition is offset\");\n        }\n    }\n\n    static Long requestedPeekOffset(\n        PeekStartPosition startPosition,\n        Long offset,\n        boolean legacyOffsetRequest,\n        long beginningOffset,\n        long endOffset\n    ) {","sourceCodeStart":2116,"sourceCodeEnd":2152,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L2116-L2152","documentation":"When startPosition is \"offset\", KafkaAgent requires an explicit offset value because it cannot infer where to start. If offset is null/missing in that mode, the driver throws this IllegalArgumentException during validatePeekRequest.","triggerScenarios":"Sending startPosition=\"offset\" without an offset field (or with JSON null) in the peek request.","commonSituations":"Switching startPosition to 'offset' in config without adding the offset field; a form where the offset input was left blank; deserializers dropping absent fields so the driver sees null.","solutions":["Provide a non-negative offset when startPosition is \"offset\".","Use startPosition \"earliest\" or \"latest\" if you don't know the offset.","Fetch a starting offset first (e.g. via offsets lookup or a prior peek result) before using startPosition=\"offset\"."],"exampleFix":"// before\n{\"startPosition\": \"offset\"}\n\n// after\n{\"startPosition\": \"offset\", \"offset\": 1284}","handlingStrategy":"validation","validationCode":"if (\"offset\".equals(startPosition) && offset == null) {\n    throw new IllegalArgumentException(\"offset is required when startPosition=offset\");\n}","typeGuard":"boolean hasRequiredOffset(String startPosition, Long offset) {\n    return !\"offset\".equals(startPosition) || offset != null;\n}","tryCatchPattern":"try {\n    return agent.peek(conn, req);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"offset is required when startPosition is offset\")) {\n        req.startPosition = \"latest\"; // degrade gracefully\n        return agent.peek(conn, req);\n    } else throw e;\n}","preventionTips":["Only use startPosition=\"offset\" when you actually have an offset value","Capture offsets from prior peek/seek results before using offset mode","Validate the full (startPosition, offset) pair as a unit, not field-by-field"],"tags":["kafka","offset","validation"],"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"}