OpenFeign/feign · error · IllegalArgumentException

target values must be absolute.

Error message

target values must be absolute.

What it means

RequestTemplate.target(String) sets the request base and requires an absolute URL containing scheme, host and port. This IllegalArgumentException is thrown when a relative value like '/api' is passed to target().

Solutions

1. Include scheme and authority: target("https://api.example.com")
2. Fix the base-url configuration value to start with http:// or https://
3. If only a path is needed, use uri() instead of target()
4. Validate configured URLs with UriUtils.isAbsolute before passing them in

Example fix

// before
template.target("api.example.com");
// after
template.target("https://api.example.com");

if (baseUrl == null || !feign.template.UriUtils.isAbsolute(baseUrl)) {
  throw new IllegalArgumentException("Base URL must be absolute, got: " + baseUrl);
}

try {
  template.target(baseUrl);
} catch (IllegalArgumentException e) {
  if ("target values must be absolute.".equals(e.getMessage())) {
    throw new ConfigurationException("BASE_URL must include scheme, e.g. https://host: " + baseUrl, e);
  }
  throw e;
}

When it happens

Trigger: Calling template.target("/api") or target("localhost:8080") — UriUtils.isAbsolute fails because there is no scheme — during manual template building or via Feign.builder().target(...) paths that call insert/create/apply.

Common situations: Configuring only a path as the base URL, environment config missing the scheme (e.g. BASE_URL=api.example.com without https://), misconfigured Target implementations.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• Target is not a valid URI.
• Status Code [ ] has already been declared to throw [ ] and…
• Method return type is not parameterized
• Wildcards are not supported for return-type parameters
• template has not been resolved.

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

Appendix: source

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

    }
    return this;
  }

  /**
   * Set the target host for this request.
   *
   * @param target host for this request. Must be an absolute target.
   * @return a RequestTemplate for chaining.
   */
  public RequestTemplate target(String target) {
    /* target can be empty */
    if (Util.isBlank(target)) {
      return this;
    }

    /* verify that the target contains the scheme, host and port */
    if (!UriUtils.isAbsolute(target)) {
      throw new IllegalArgumentException("target values must be absolute.");
    }
    if (target.endsWith("/")) {
      target = target.substring(0, target.length() - 1);
    }
    try {
      /* parse the target */
      URI targetUri = URI.create(target);

      if (Util.isNotBlank(targetUri.getRawQuery())) {
        /*
         * target has a query string, we need to make sure that they are recorded as queries
         */
        this.extractQueryTemplates(targetUri.getRawQuery(), true);
      }

      /* strip the query string */
      this.target =
          targetUri.getScheme() + "://" + targetUri.getRawAuthority() + targetUri.getRawPath();

View on GitHub (pinned to e2a1e27560)