OpenFeign/feign · error · IllegalArgumentException

template is required.

Error message

template is required.

What it means

feign.template.Template is the base class for URI/header/body templates. Its constructor throws IllegalArgumentException('template is required.') when the template string value is null. A null template has no meaning — there is nothing to parse into literals and expressions — so construction fails immediately.

Solutions

1. Validate the template string is non-null before constructing; supply a sensible default (e.g. "/") if the source can be absent.
2. Fix the upstream source of the template (missing annotation value, missing config key) so a real template string is provided.
3. Wrap Template creation in try-catch for IllegalArgumentException and convert it into a configuration error message naming the missing template.

Example fix

// before
Template template = new UriTemplate(path, false, false); // path may be null
// after
Objects.requireNonNull(path, "template path must not be null");
Template template = new UriTemplate(path, false, false);

if (templateValue == null) {
  throw new IllegalArgumentException("template value must not be null (check configuration)");
}

static boolean isValidTemplate(String s) {
  return s != null;
}

try {
  Template t = new UriTemplate(value, false, false);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Template value was null; check config/annotations", e);
}

When it happens

Trigger: Passing a null value to the Template constructor or to subclasses that forward it (UriTemplate, HeaderTemplate body, etc.), typically when a template string comes from a nullable source: annotation values obtained reflectively, config lookups, or RequestTemplate paths that resolved to null.

Common situations: Custom Contract implementations reading annotation values that are null; building Feign targets/URIs from configuration where a base URL or path key is missing; generic template-building utilities with unvalidated inputs.

Related errors

• a value is required.
• name is required.
• values are required
• an expression 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/b33836a033e76c48. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/feign/template/Template.java:59

  private final Charset charset;
  private final List<TemplateChunk> templateChunks = new ArrayList<>();

  /**
   * Create a new Template.
   *
   * @param value of the template.
   * @param allowUnresolved if unresolved expressions should remain.
   * @param encode all values.
   * @param encodeSlash if slash characters should be encoded.
   */
  Template(
      String value,
      ExpansionOptions allowUnresolved,
      EncodingOptions encode,
      boolean encodeSlash,
      Charset charset) {
    if (value == null) {
      throw new IllegalArgumentException("template is required.");
    }
    this.template = value;
    this.allowUnresolved = ExpansionOptions.ALLOW_UNRESOLVED == allowUnresolved;
    this.encode = encode;
    this.encodeSlash = encodeSlash;
    this.charset = charset;
    this.parseTemplate();
  }

  /**
   * Create a new Template from the provided {@link TemplateChunk}s.
   *
   * @param allowUnresolved if unresolved expressions should remain.
   * @param encode all values
   * @param encodeSlash if slash characters should be encoded.
   * @param charset of the result.
   * @param chunks for this template.
   */

View on GitHub (pinned to e2a1e27560)