OpenFeign/feign · error · IllegalArgumentException

expression is too long. Max length

Error message

expression is too long. Max length: {maxExpressionLength}

What it means

Feign's template parser limits how long a single URI template expression ({...}) may be, for safety and to avoid pathological regex building. The limit defaults via the 'feign.template.expression.maxLength' system property and can be disabled by setting it to a non-positive value. When the expression text between braces exceeds that length, Expressions.create throws this IllegalArgumentException before compiling the expression.

Solutions

Shorten the expression: move large values out of the URI template and pass them via request body or headers instead.
Raise or disable the limit by setting system property -Dfeign.template.expression.maxLength=-1 (disable) or a larger positive value.
Check that you are not re-parsing already-expanded URLs; mark literals with RequestTemplate.literal or escape braces.
Sanitize/truncate user input before placing it into template variables.

Example fix

// before
RequestTemplate tpl = new RequestTemplate().append("/search?filter={filter}");
tpl.resolve(Collections.singletonMap("filter", hugeJsonString)); // expression too long
// after
RequestTemplate tpl = new RequestTemplate().append("/search");
tpl.query("filter", hugeJsonString); // plain value, not a template expression

Defensive patterns

Strategy: validation

Validate before calling

int max = Math.max(Integer.getInteger("feign.template.expression.maxLength", 1000), 0);
if (expression != null && expression.length() > max) {
  throw new IllegalArgumentException("expression exceeds " + max + " chars");
}

Type guard

static boolean safeExpression(String e) {
  int max = Integer.getInteger("feign.template.expression.maxLength", 1000);
  return max <= 0 || (e != null && e.length() <= max);
}

Try / catch

try {
  template.resolve(variables);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("expression is too long")) {
    // fall back to body/POST or truncate value
  } else throw e;
}

Prevention

Keep large payloads out of URI expressions — use body or query values appended directly.
Never re-parse already-expanded URLs as templates.
Set feign.template.expression.maxLength deliberately in your environment and document it.
Truncate or reject oversized user input before template resolution.

When it happens

Trigger: Calling RequestTemplate.append/insert or resolving a URI whose {...} expression is longer than the configured max (default 1000 chars); building templates programmatically with very large variable sub-patterns; passing user-supplied strings into template variables that themselves become expressions.

Common situations: Interpolating large JSON or base64 blobs into URL placeholders; misconfigured system property 'feign.template.expression.maxLength'; accidental double-template-processing where an already-expanded URL containing braces gets re-parsed as a template; dynamically generated query expressions from untrusted input.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/feign/template/Expressions.java:92

          "(([\\w-\\[\\]$]|%[0-9A-Fa-f]{2})(\\.?([\\w-\\[\\]$]|%[0-9A-Fa-f]{2}))*(:.*|\\*)?)(,(([\\w-\\[\\]$]|%[0-9A-Fa-f]{2})(\\.?([\\w-\\[\\]$]|%[0-9A-Fa-f]{2}))*(:.*|\\*)?))*");

  public static Expression create(final String value) {

    /* remove the start and end braces */
    final String expression = stripBraces(value);
    if (expression == null || expression.isEmpty()) {
      throw new IllegalArgumentException("an expression is required.");
    }

    /*
     * Check if the expression is too long. The limit is configurable through the
     * "feign.template.expression.maxLength" system property and can be disabled by setting it to a
     * non-positive value.
     */
    final int maxExpressionLength =
        Integer.getInteger(MAX_EXPRESSION_LENGTH_PROPERTY, DEFAULT_MAX_EXPRESSION_LENGTH);
    if (maxExpressionLength > 0 && expression.length() > maxExpressionLength) {
      throw new IllegalArgumentException(
          "expression is too long. Max length: " + maxExpressionLength);
    }

    /* create a new regular expression matcher for the expression */
    String variableName = null;
    String variablePattern = null;
    String operator = null;
    Matcher matcher = EXPRESSION_PATTERN.matcher(value);
    if (matcher.matches()) {
      /* grab the operator */
      operator = matcher.group(2).trim();

      /* we have a valid variable expression, extract the name from the first group */
      variableName = matcher.group(3).trim();
      if (variableName.contains(":")) {
        /* split on the colon and ensure the size of parts array must be 2 */
        String[] parts = variableName.split(":", 2);
        variableName = parts[0];

View on GitHub (pinned to e2a1e27560)