{"record":{"id":"0540b8b72b5f4a37","repo":"t8y2/dbx","slug":"partition-must-be-non-negative","errorCode":null,"errorMessage":"partition must be non-negative","messagePattern":"partition must be non-negative","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java","lineNumber":2123,"sourceCode":"        if (value == null) {\n            return PeekStartPosition.EARLIEST;\n        }\n        return switch (value.trim().toLowerCase(Locale.ROOT)) {\n            case \"earliest\" -> PeekStartPosition.EARLIEST;\n            case \"latest\" -> PeekStartPosition.LATEST;\n            case \"offset\" -> PeekStartPosition.OFFSET;\n            default -> throw new IllegalArgumentException(\"Unsupported peek startPosition: \" + value);\n        };\n    }\n\n    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) {","sourceCodeStart":2105,"sourceCodeEnd":2141,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L2105-L2141","documentation":"validatePeekRequest checks that, when supplied, the peek partition index is >= 0. Kafka partitions are zero-based, so a negative value can never be valid. The driver throws this IllegalArgumentException before touching the cluster.","triggerScenarios":"Passing partition = -1 (often as a sentinel for 'any partition' or 'unset') to the peek API along with other parameters.","commonSituations":"Using -1 as a 'not specified' default in client code; converting an unsigned UI value with an error sentinel; SQL-influenced code where -1 sometimes means 'all'.","solutions":["Pass null (omit the field) instead of -1 when no partition should be pinned.","Ensure the client serializes partition as null rather than a sentinel negative number.","Clamp/validate partition >= 0 before sending the request."],"exampleFix":"// before\nInteger partition = unset ? -1 : userPartition;\nagent.peek(conn, topic, partition);\n\n// after\nInteger partition = unset ? null : userPartition;\nagent.peek(conn, topic, partition);","handlingStrategy":"validation","validationCode":"if (partition != null && partition < 0) {\n    throw new IllegalArgumentException(\"partition must be >= 0 or null\");\n}","typeGuard":"boolean isValidPartition(Integer partition) { return partition == null || partition >= 0; }","tryCatchPattern":"try {\n    return agent.peek(conn, topic, partition);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().equals(\"partition must be non-negative\")) {\n        return agent.peek(conn, topic, null); // treat sentinel as unset\n    } else throw e;\n}","preventionTips":["Use null, not -1, to represent 'no partition specified'","Normalize sentinel values at deserialization time","Type partition as Integer (nullable) in client DTOs"],"tags":["kafka","partition","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"}