provectus/kafka-ui · error · IllegalArgumentException

Wrong seekTo argument format. See API docs for details

Error message

Wrong seekTo argument format. See API docs for details

What it means

Thrown by the generic validation guard at the head of MessagesController.parseSeekTo when a non-null, non-empty seekTo list contains an element whose format cannot be split into the expected '[partition]::[offset]' or '[partition]::[timestamp in millis]' shape. The offending input is one of the seekTo strings passed alongside seekType=OFFSET or TIMESTAMP; the error fires during streaming when splitting the element does not yield a parseable partition/offset pair, and the API caller must correct the seekTo element format.

Solutions

  1. Format every seekTo item as `<partition>::<offset or timestampMillis>`, e.g. `0::42`
  2. Check URL encoding — '::' is valid in query strings, don't double-encode it
  3. Validate the list client-side before sending the request

Example fix

// before
seekTo=0:42
// after
seekTo=0::42
Defensive patterns

Strategy: validation

Validate before calling

function validateSeekTo(entries) {
  return entries.every(e => /^[0-9]+::[0-9]+$/.test(e));
}
if (!validateSeekTo(seekTo)) throw new Error('seekTo entries must be partition::value');

Type guard

const isValidSeekTo = (v) => typeof v === 'string' && /^[0-9]+::[0-9]+$/.test(v);

Try / catch

try {
  const res = await api.getMessages({ seekTo });
} catch (e) {
  if (e.status === 400 && /Wrong seekTo/.test(e.message)) {
    seekTo = seekTo.map(normalizeToPartitionValueFormat);
  }
}

Prevention

When it happens

Trigger: Passing seekTo values without the '::' separator, e.g. `0-42`, `0`, or full URLs/JSON fragments instead of `partition::value`.

Common situations: Manual query construction missing the double-colon; encoding issues where '::' got mangled; copying values from other tools that use a different separator.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of provectus/kafka-ui@83b5a60cc0 (2026-09-08). Data as JSON: /api/errors/a1781b603033b9f4. Report an issue: GitHub.

Appendix: source

Thrown at kafka-ui-api/src/main/java/com/provectus/kafka/ui/controller/MessagesController.java:166

  }

  /**
   * The format is [partition]::[offset] for specifying offsets
   * or [partition]::[timestamp in millis] for specifying timestamps.
   */
  @Nullable
  private Map<TopicPartition, Long> parseSeekTo(String topic, SeekTypeDTO seekType, List<String> seekTo) {
    if (seekTo == null || seekTo.isEmpty()) {
      if (seekType == SeekTypeDTO.LATEST || seekType == SeekTypeDTO.BEGINNING) {
        return null;
      }
      throw new ValidationException("seekTo should be set if seekType is " + seekType);
    }
    return seekTo.stream()
        .map(p -> {
          String[] split = p.split("::");
          if (split.length != 2) {
            throw new IllegalArgumentException(
                "Wrong seekTo argument format. See API docs for details");
          }

          return Pair.of(
              new TopicPartition(topic, Integer.parseInt(split[0])),
              Long.parseLong(split[1])
          );
        })
        .collect(toMap(Pair::getKey, Pair::getValue));
  }

  @Override
  public Mono<ResponseEntity<TopicSerdeSuggestionDTO>> getSerdes(String clusterName,
                                                                 String topicName,
                                                                 SerdeUsageDTO use,
                                                                 ServerWebExchange exchange) {
    var context = AccessContext.builder()
        .cluster(clusterName)

View on GitHub (pinned to 83b5a60cc0)