{"record":{"id":"db27f66db2743130","repo":"t8y2/dbx","slug":"offset-is-required-when-startposition-is-offset","errorCode":null,"errorMessage":"offset is required when startPosition is offset","messagePattern":"offset is required 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":2139,"sourceCode":"    ) {\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    ) {\n        return switch (startPosition) {\n            case LATEST -> endOffset > beginningOffset ? beginningOffset : null;\n            case OFFSET -> offset;\n            case EARLIEST -> legacyOffsetRequest ? offset : beginningOffset;\n        };","sourceCodeStart":2121,"sourceCodeEnd":2157,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L2121-L2157","documentation":"Completing the same validation chain as errors 96-97: when startPosition is \"offset\" and an offset is supplied, it must be >= 0. Negative offsets have no meaning in Kafka, so the driver throws this IllegalArgumentException with the mode-specific message.","triggerScenarios":"Sending startPosition=\"offset\" with offset = -1 or any negative number.","commonSituations":"Using -1 to mean 'latest' or 'end' (a convention from other systems, e.g. some consumer APIs use -1/-2 sentinels); signed/unsigned arithmetic wrapping; user typing a negative offset in a tool.","solutions":["Pass a non-negative absolute offset with startPosition=\"offset\".","Use startPosition=\"latest\" or \"earliest\" instead of negative sentinel offsets.","Validate offset >= 0 in client code before constructing the request."],"exampleFix":"// before\n{\"startPosition\": \"offset\", \"offset\": -1} // meant 'latest'\n\n// after\n{\"startPosition\": \"latest\"}","handlingStrategy":"validation","validationCode":"if (\"offset\".equals(startPosition) && offset != null && offset < 0) {\n    throw new IllegalArgumentException(\"offset must be >= 0 when startPosition=offset\");\n}","typeGuard":"boolean isValidOffsetForOffsetMode(String startPosition, Long offset) {\n    return !\"offset\".equals(startPosition) || (offset != null && offset >= 0);\n}","tryCatchPattern":"try {\n    return agent.peek(conn, req);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"offset must be non-negative when startPosition is offset\")) {\n        req.startPosition = \"latest\";\n        req.offset = null;\n        return agent.peek(conn, req);\n    } else throw e;\n}","preventionTips":["Never use negative sentinels (-1/-2) for 'latest'/'earliest'; use the named start positions","Clamp or reject negative offsets in your client before sending","Add a shared (startPosition, offset) validator reused by all request builders"],"tags":["kafka","offset","validation"],"backgroundTag":"parameter-out-of-range","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}