{"record":{"id":"78316028cb3bf0c0","repo":"t8y2/dbx","slug":"offset-must-be-non-negative-when-startposition-is","errorCode":null,"errorMessage":"offset must be non-negative when startPosition is offset","messagePattern":"offset must be non-negative 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":2142,"sourceCode":"        }\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        };\n    }\n\n    static int peekScanLimit(int count, int readablePartitionCount) {","sourceCodeStart":2124,"sourceCodeEnd":2160,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L2124-L2160","documentation":"This is the non-legacy branch of validatePeekRequest for negative offsets. When an explicit startPosition is present and equals \"offset\", a supplied offset below zero is rejected with this IllegalArgumentException. It mirrors error 98 but runs on the explicit-startPosition code path.","triggerScenarios":"Peek request with explicit startPosition=\"offset\" and a negative offset value (e.g. -1 used as a sentinel).","commonSituations":"Porting code from the legacy bare-offset API where -1 sometimes meant 'auto'; front-end defaults of -1 for 'unset'; mixing legacy and new request shapes so both validation branches fire differently.","solutions":["Use offset >= 0 with startPosition=\"offset\".","Omit startPosition and use \"earliest\"/\"latest\" semantics instead of negative sentinels.","Add client-side validation mirroring validatePeekRequest before sending."],"exampleFix":"// before\npeek(topic, /* partition */ 0, /* startPosition */ \"offset\", /* offset */ -5);\n\n// after\npeek(topic, 0, \"offset\", 0L); // or use startPosition \"latest\"","handlingStrategy":"validation","validationCode":"if (offset != null && offset < 0) {\n    throw new IllegalArgumentException(\"offset must be non-negative\");\n}","typeGuard":"boolean isNonNegativeOffset(Long offset) { return offset == null || offset >= 0; }","tryCatchPattern":"try {\n    return agent.peek(conn, req);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"offset must be non-negative\")) {\n        req.offset = Math.max(req.offset, 0L); // or fall back to earliest\n        return agent.peek(conn, req);\n    } else throw e;\n}","preventionTips":["Run validatePeekRequest-equivalent checks client-side before every peek call","Ensure migrated legacy requests convert negative sentinel offsets to named start positions","Test your request builder against the driver's full validation chain (partition, offset, startPosition)"],"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-14T05:17:10.506Z"}