OpenFeign/feign · error · IllegalArgumentException

name is required.

Error message

name is required.

What it means

QueryTemplate.create() builds a query-string template from a name, values, charset, collection format, and slash-encoding option. It validates the name first with Util.isBlank and throws IllegalArgumentException('name is required.') when the name is null, empty, or whitespace-only. A query parameter must have a name to be rendered in the URL.

Solutions

1. Ensure every query parameter name passed to RequestTemplate.query / QueryTemplate.create is a non-blank string before invoking.
2. Filter entries of a @QueryMap (or any Map used for query params) to skip keys that are null/empty/whitespace.
3. Check the interface method's annotations: fix blank @RequestLine or query annotation values at the source.

Example fix

// before
requestTemplate.query(param.getKey(), Collections.singletonList(param.getValue())); // key may be blank
// after
if (!Util.isBlank(param.getKey())) {
  requestTemplate.query(param.getKey(), Collections.singletonList(param.getValue()));
}

if (Util.isBlank(name)) {
  throw new IllegalArgumentException("query parameter name must not be blank");
}
requestTemplate.query(name, values);

static boolean isUsableParamName(String name) {
  return name != null && !name.trim().isEmpty();
}

try {
  requestTemplate.query(name, values);
} catch (IllegalArgumentException e) {
  throw new ConfigException("Blank query parameter name in request template", e);
}

When it happens

Trigger: Calling QueryTemplate.create(null/""/" ", values, ...) directly, or indirectly via RequestTemplate.query(name, values) / append() when a query parameter name resolved to blank — e.g. from a custom Contract or @QueryMap with empty keys, or annotation value placeholders that expanded to empty.

Common situations: Custom Client/Contract implementations constructing query templates programmatically; @QueryMap maps with empty-string keys; interface methods with blank annotation values (e.g. @RequestLine("GET /?=")).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• values are required
• template is required.
• a value is required.
• Status Code [ ] has already been declared to throw [ ] and…
• Cannot generate exception - check constructor parameter…

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/f6a7e2ac5fdb7069. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/feign/template/QueryTemplate.java:77

  /**
   * Create a new Query Template.
   *
   * @param name of the query parameter.
   * @param values in the template.
   * @param charset for the template.
   * @param collectionFormat to use.
   * @param decodeSlash if slash characters should be decoded
   * @return a QueryTemplate
   */
  public static QueryTemplate create(
      String name,
      Iterable<String> values,
      Charset charset,
      CollectionFormat collectionFormat,
      boolean decodeSlash) {
    if (Util.isBlank(name)) {
      throw new IllegalArgumentException("name is required.");
    }

    if (values == null) {
      throw new IllegalArgumentException("values are required");
    }

    /* remove all empty values from the array */
    Collection<String> remaining =
        StreamSupport.stream(values.spliterator(), false)
            .filter(Util::isNotBlank)
            .collect(Collectors.toList());

    return new QueryTemplate(name, remaining, charset, collectionFormat, decodeSlash);
  }

  /**
   * Append a value to the Query Template.
   *

View on GitHub (pinned to e2a1e27560)