OpenFeign/feign · error · IllegalStateException

template has not been resolved.

Error message

template has not been resolved.

What it means

RequestTemplate.request() builds the immutable Request, but only after the template has been resolved (URI template variables substituted). This IllegalStateException is thrown when request() is called on a template that still contains unresolved placeholders.

Solutions

1. Call template.resolve(variables) (or let Feign's SynchronousMethodHandler do it) before calling request()
2. If you only need the unresolved URL string, use the template's url/toString() for diagnostics instead of request()
3. In custom interceptors, operate on the already-resolved Request (targetRequest) rather than the raw template
4. Ensure your code path does not skip TargetRequestTemplate resolution steps

Example fix

// before
Request req = template.request(); // IllegalStateException
// after
Request req = template.resolve(Collections.singletonMap("id", "42")).request();

if (!template.isResolved()) {
  throw new IllegalStateException("Call resolve() before request()");
}

boolean usable = template.isResolved(); // only build a Request when true

try {
  Request req = template.request();
} catch (IllegalStateException e) {
  if ("template has not been resolved.".equals(e.getMessage())) {
    template = template.resolve(myVariables);
    Request req = template.request();
  } else { throw e; }
}

When it happens

Trigger: Calling requestTemplate.request() (directly or via apply()/toString() paths that require a resolved template) before invoking resolve(Map<String,Object>) or executeAndDecode — i.e. building the Request manually while template variables remain unsubstituted.

Common situations: Custom Client or interceptor code reading template.request() too early, unit tests asserting on the Request before resolving, or using the deprecated apply() flow out of order.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Method return type is not parameterized
• Wildcards are not supported for return-type parameters
• Invalid HTTP Method
• url values must be not be absolute.
• target values must be absolute.

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

Appendix: source

Thrown at core/src/main/java/feign/RequestTemplate.java:289

   * @deprecated use {@link RequestTemplate#resolve(Map)}. Values already encoded are recognized as
   *     such and skipped.
   */
  @SuppressWarnings("unused")
  @Deprecated
  RequestTemplate resolve(Map<String, ?> unencoded, Map<String, Boolean> alreadyEncoded) {
    return this.resolve(unencoded);
  }

  /**
   * Creates a {@link Request} from this template. The template must be resolved before calling this
   * method, or an {@link IllegalStateException} will be thrown.
   *
   * @return a new Request instance.
   * @throws IllegalStateException if this template has not been resolved.
   */
  public Request request() {
    if (!this.resolved) {
      throw new IllegalStateException("template has not been resolved.");
    }
    return Request.create(this.method, this.url(), this.headers(), this.body, this);
  }

  /**
   * Set the Http Method.
   *
   * @param method to use.
   * @return a RequestTemplate for chaining.
   * @deprecated see {@link RequestTemplate#method(HttpMethod)}
   */
  @Deprecated
  public RequestTemplate method(String method) {
    checkNotNull(method, "method");
    try {
      this.method = HttpMethod.valueOf(method);
    } catch (IllegalArgumentException iae) {
      throw new IllegalArgumentException("Invalid HTTP Method: " + method);

View on GitHub (pinned to e2a1e27560)