t8y2/dbx · error · IllegalArgumentException

Unsupported peek startPosition: ${value}

Error message

Unsupported peek startPosition: ${value}

What it means

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.

Source

Thrown at agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java:2112

    }

    enum PeekStartPosition {
        EARLIEST,
        LATEST,
        OFFSET,
    }

    /** Omitting startPosition preserves the old earliest default (or explicit legacy offset) behavior. */
    static PeekStartPosition peekStartPosition(JsonObject params) {
        String value = stringOrNull(params, "startPosition");
        if (value == null) {
            return PeekStartPosition.EARLIEST;
        }
        return switch (value.trim().toLowerCase(Locale.ROOT)) {
            case "earliest" -> PeekStartPosition.EARLIEST;
            case "latest" -> PeekStartPosition.LATEST;
            case "offset" -> PeekStartPosition.OFFSET;
            default -> throw new IllegalArgumentException("Unsupported peek startPosition: " + value);
        };
    }

    static void validatePeekRequest(
        PeekStartPosition startPosition,
        boolean explicitStartPosition,
        Integer partition,
        Long offset
    ) {
        if (partition != null && partition < 0) {
            throw new IllegalArgumentException("partition must be non-negative");
        }
        if (!explicitStartPosition) {
            // Older clients used offset directly without a startPosition field.
            if (offset != null && offset < 0) {
                throw new IllegalArgumentException("offset must be non-negative");
            }
            return;

View on GitHub (pinned to c0390bff16)

Solutions

1. Use exactly one of "earliest", "latest", or "offset" for startPosition.
2. If you meant the beginning of the topic, use "earliest" (Kafka terminology), not "beginning".
3. Trim/lowercase and whitelist-map values in your client before sending them.

Example fix

// before
request.startPosition = "beginning";

// after
request.startPosition = "earliest";

Set<String> ALLOWED = Set.of("earliest", "latest", "offset");
if (startPosition != null && !ALLOWED.contains(startPosition.trim().toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException("startPosition must be one of " + ALLOWED);
}

boolean isValidStartPosition(String s) {
    return s == null || Set.of("earliest", "latest", "offset").contains(s.trim().toLowerCase(Locale.ROOT));
}

try {
    return agent.peek(conn, req);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unsupported peek startPosition")) {
        req.startPosition = "earliest";
        return agent.peek(conn, req);
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• offsets must be an array
• Peek message count must be between 1 and " + MAX_PEEK_MESSAG
• ${name} must be a positive integer
• Kafka partition ${partition} does not exist for topic '${top
• partition must be non-negative

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/147cbbe6a6654f3e. Report an issue: GitHub.