{"record":{"id":"2f99e584e3261a91","repo":"t8y2/dbx","slug":"offset-must-be-non-negative","errorCode":null,"errorMessage":"offset must be non-negative","messagePattern":"offset 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":2128,"sourceCode":"            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) {\n            throw new IllegalArgumentException(\"offset must be non-negative when startPosition is offset\");\n        }\n    }\n\n    static Long requestedPeekOffset(","sourceCodeStart":2110,"sourceCodeEnd":2146,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L2110-L2146","documentation":"In validatePeekRequest, an explicit offset is only meaningful when startPosition is \"offset\" (the legacy path without startPosition also allows a bare offset). If startPosition is earliest/latest and an offset is also provided, the driver throws this IllegalArgumentException because the two settings conflict.","triggerScenarios":"Sending a peek request with startPosition=\"latest\" (or \"earliest\") while also including an offset field; a client library that always serializes a default offset of 0 alongside startPosition.","commonSituations":"Persisted request templates that kept a stale offset field after switching startPosition to latest; ORM/serializer defaults populating offset automatically; copy-paste between the offset-based and earliest/latest request styles.","solutions":["Remove the offset field from the request when startPosition is earliest or latest.","If you need a specific offset, set startPosition to \"offset\" and supply the offset.","Ensure your serialization layer omits null/unused fields instead of sending defaults."],"exampleFix":"// before\n{\"startPosition\": \"latest\", \"offset\": 42}\n\n// after\n{\"startPosition\": \"latest\"}","handlingStrategy":"validation","validationCode":"if (offset != null && !\"offset\".equals(startPosition)) {\n    throw new IllegalArgumentException(\"offset requires startPosition=offset\");\n}","typeGuard":"boolean isConsistentPeekRequest(String startPosition, Long offset) {\n    return offset == null || \"offset\".equals(startPosition);\n}","tryCatchPattern":"try {\n    return agent.peek(conn, req);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"offset is only supported when startPosition is offset\")) {\n        req.offset = null;\n        return agent.peek(conn, req);\n    } else throw e;\n}","preventionTips":["Build peek requests through a single factory that strips offset unless startPosition=\"offset\"","Configure serializers to omit null fields rather than emit defaults","Audit saved request templates for stale offset fields"],"tags":["kafka","offset","conflicting-parameters"],"backgroundTag":"conflicting-parameters","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"}