{"record":{"id":"147cbbe6a6654f3e","repo":"t8y2/dbx","slug":"unsupported-peek-startposition-value","errorCode":null,"errorMessage":"Unsupported peek startPosition: ${value}","messagePattern":"Unsupported peek startPosition: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java","lineNumber":2112,"sourceCode":"    }\n\n    enum PeekStartPosition {\n        EARLIEST,\n        LATEST,\n        OFFSET,\n    }\n\n    /** Omitting startPosition preserves the old earliest default (or explicit legacy offset) behavior. */\n    static PeekStartPosition peekStartPosition(JsonObject params) {\n        String value = stringOrNull(params, \"startPosition\");\n        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;","sourceCodeStart":2094,"sourceCodeEnd":2130,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java#L2094-L2130","documentation":"KafkaAgent parses the peek request's startPosition as an enum-like string limited to \"earliest\", \"latest\", and \"offset\" (case-insensitive, trimmed). Any other value throws this IllegalArgumentException. The enum PeekStartPosition drives where the peek consumer begins reading.","triggerScenarios":"Passing startPosition values such as \"beginning\", \"end\", \"first\", \" Earliest \"+typo, \"OFFSET \" with casing is fine but e.g. \"newest\"/\"oldest\" are rejected, in the peek request body.","commonSituations":"Migrating from other queue APIs that use 'beginning'/'end' terminology; old clients sending numeric start positions; case or whitespace handled but misspelled values like 'earlies' slipping through.","solutions":["Use exactly one of \"earliest\", \"latest\", or \"offset\" for startPosition.","If you meant the beginning of the topic, use \"earliest\" (Kafka terminology), not \"beginning\".","Trim/lowercase and whitelist-map values in your client before sending them."],"exampleFix":"// before\nrequest.startPosition = \"beginning\";\n\n// after\nrequest.startPosition = \"earliest\";","handlingStrategy":"validation","validationCode":"Set<String> ALLOWED = Set.of(\"earliest\", \"latest\", \"offset\");\nif (startPosition != null && !ALLOWED.contains(startPosition.trim().toLowerCase(Locale.ROOT))) {\n    throw new IllegalArgumentException(\"startPosition must be one of \" + ALLOWED);\n}","typeGuard":"boolean isValidStartPosition(String s) {\n    return s == null || Set.of(\"earliest\", \"latest\", \"offset\").contains(s.trim().toLowerCase(Locale.ROOT));\n}","tryCatchPattern":"try {\n    return agent.peek(conn, req);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Unsupported peek startPosition\")) {\n        req.startPosition = \"earliest\";\n        return agent.peek(conn, req);\n    } else throw e;\n}","preventionTips":["Map external terminology ('beginning'/'end') to Kafka terms ('earliest'/'latest') in your client layer","Use a shared enum type for startPosition instead of free-form strings","Normalize (trim/lowercase) user input before sending"],"tags":["kafka","enum","validation"],"backgroundTag":"invalid-enum-value","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"}