OpenFeign/feign · error · IllegalArgumentException

variable map is required.

Error message

variable map is required.

What it means

Template.expand() requires a non-null variables map to perform URI template expansion. The library throws IllegalArgumentException immediately when null is passed because expansion without a variable map is undefined; callers should pass an empty map if there are no variables.

Solutions

1. Pass an empty map (Collections.emptyMap()) instead of null when there are no variables
2. Null-check or default the variables map before calling expand
3. Find the upstream code producing null (e.g. a failed parameter lookup) and fix it

Example fix

// before
template.expand(null);
// after
template.expand(Collections.emptyMap());

if (variables == null) {
  variables = Collections.emptyMap();
}
String uri = template.expand(variables);

boolean safeToExpand(Map<String, ?> vars) { return vars != null; }

try {
  template.expand(vars);
} catch (IllegalArgumentException e) {
  // fall back to empty map or log config error
}

When it happens

Trigger: Calling Template.expand(null) directly, or indirectly through RequestTemplates.expand when a null variable map reaches the template engine.

Common situations: Custom Target/RequestInterceptor code building templates manually; refactors where a variables map becomes null because an upstream lookup returned null; unit tests exercising expand with null.

Related errors

• an expression is required.
• template is required.
• formatted errorMessageTemplate with errorMessageArgs
• expression is too long. Max length
• Value does not match the expression pattern

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

Appendix: source

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

      Charset charset,
      List<TemplateChunk> chunks) {
    this.templateChunks.addAll(chunks);
    this.allowUnresolved = ExpansionOptions.ALLOW_UNRESOLVED == allowUnresolved;
    this.encode = encode;
    this.encodeSlash = encodeSlash;
    this.charset = charset;
    this.template = this.toString();
  }

  /**
   * Expand the template.
   *
   * @param variables containing the values for expansion.
   * @return a fully qualified URI with the variables expanded.
   */
  public String expand(Map<String, ?> variables) {
    if (variables == null) {
      throw new IllegalArgumentException("variable map is required.");
    }

    /* resolve all expressions within the template */
    StringBuilder resolved = null;
    for (TemplateChunk chunk : this.templateChunks) {
      String expanded;
      if (chunk instanceof Expression) {
        expanded = this.resolveExpression((Expression) chunk, variables);
      } else {
        /* chunk is a literal value */
        expanded = chunk.getValue();
      }
      if (expanded == null) {
        continue;
      }

      /* append it to the result */
      if (resolved == null) {

View on GitHub (pinned to e2a1e27560)