OpenFeign/feign · error · IllegalArgumentException

values are required

Error message

values are required

What it means

QueryTemplate.create() also validates the values parameter, throwing IllegalArgumentException('values are required') when it is null. A query template with no value collection at all cannot be constructed (blank individual values are filtered later, but the collection itself must exist).

Solutions

1. Substitute an empty collection (Collections.emptyList()) when the values source is null, so the template is still created and blank values are filtered naturally.
2. Guard the call site: skip calling query()/create() when the value list is null.
3. Catch IllegalArgumentException at a boundary that processes untrusted parameter maps and log/skip the offending parameter.

Example fix

// before
requestTemplate.query(name, params.get(name)); // null when key missing
// after
List<String> values = params.getOrDefault(name, Collections.emptyList());
requestTemplate.query(name, values);

Iterable<String> safeValues = (values == null) ? Collections.emptyList() : values;
QueryTemplate.create(name, safeValues, charset, collectionFormat, decodeSlash);

static Iterable<String> orEmpty(Iterable<String> values) {
  return values == null ? Collections.emptyList() : values;
}

try {
  requestTemplate.query(name, values);
} catch (IllegalArgumentException e) {
  // values was null: default to empty collection or skip parameter
}

When it happens

Trigger: Calling QueryTemplate.create(name, null, charset, collectionFormat, decodeSlash), or RequestTemplate.query(name, (Iterable) null) / append() with a null values iterable — often from a map lookup that returned null instead of an empty collection.

Common situations: Passing params.get(key) (null when key absent) directly into query(); custom Contract code assembling query parameters from nullable lists; interceptor code adding query params from optional configuration.

Related errors

• name is 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/df3b396fda794d3b. Report an issue: GitHub.

Appendix: source

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

   * @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.
   *
   * @param queryTemplate to append to.
   * @param values to append.
   * @return a new QueryTemplate with value appended.
   */

View on GitHub (pinned to e2a1e27560)