OpenFeign/feign · error · IllegalArgumentException

values are required

Error message

values are required

What it means

HeaderTemplate.create requires a values collection; a null Iterable means the template would have no values to expand, so Feign rejects it with this IllegalArgumentException. Note that only null is rejected — an empty Iterable is accepted and simply yields a header with no values.

Solutions

1. Pass Collections.emptyList() instead of null when there are no values.
2. Coalesce null collections: values == null ? Collections.emptyList() : values.
3. Fix the upstream source (Map.getOrDefault, Optional) so it returns an empty collection.
4. Check for null before calling create and skip the header.

Example fix

// before
HeaderTemplate.create("X-Custom", headersByName.get("custom")); // may be null
// after
List<String> vals = headersByName.getOrDefault("custom", Collections.emptyList());
HeaderTemplate.create("X-Custom", vals);

List<String> safe = values == null ? Collections.emptyList() : values;
HeaderTemplate.create(name, safe);

static <T> Iterable<T> nonNull(Iterable<T> it) { return it == null ? Collections.emptyList() : it; }

try {
  tpl.header(name, values);
} catch (IllegalArgumentException e) {
  if (e.getMessage().equals("values are required")) {
    tpl.header(name, Collections.emptyList());
  } else throw e;
}

When it happens

Trigger: Calling HeaderTemplate.create(name, null); passing a map lookup result that was null because the key was absent; append(name, null) on an existing HeaderTemplate.

Common situations: Collections built from optional config (Map.get returning null); deserialized header maps missing a key; methods returning null instead of empty collections.

Related errors

• name is required.
• name is required.
• values are required
• template is required.
• Status Code [ ] has already been declared to throw [ ] and…

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

Appendix: source

Thrown at core/src/main/java/feign/template/HeaderTemplate.java:47

import java.util.stream.Collectors;
import java.util.stream.StreamSupport;

/**
 * Template for HTTP Headers. Variables that are unresolved are ignored and Literals are not
 * encoded.
 */
public final class HeaderTemplate {

  private final String name;
  private final List<Template> values = new CopyOnWriteArrayList<>();

  public static HeaderTemplate create(String name, Iterable<String> values) {
    if (name == null || name.isEmpty()) {
      throw new IllegalArgumentException("name is required.");
    }

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

    return new HeaderTemplate(name, values, Util.UTF_8);
  }

  public static HeaderTemplate literal(String name, Iterable<String> values) {
    if (name == null || name.isEmpty()) {
      throw new IllegalArgumentException("name is required.");
    }

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

    return new HeaderTemplate(name, values, Util.UTF_8, true);
  }

  /**

View on GitHub (pinned to e2a1e27560)