OpenFeign/feign · error · IllegalArgumentException

url values must be not be absolute.

Error message

url values must be not be absolute.

What it means

RequestTemplate.uri(String, boolean) only accepts relative URIs because the absolute base (scheme, host, port) is supplied separately via target(). This IllegalArgumentException is thrown when an absolute URL like 'https://host/path' is passed to uri().

Solutions

1. Split the URL: put 'https://api.example.com' in target() and '/users' in uri()
2. Strip the scheme+authority before passing to uri()
3. Use RequestTemplate.target(absoluteUrl) for the base and keep the path relative
4. In Target implementations, ensure the path returned is relative (Target.EmptyTarget/HardCodedTarget patterns)

Example fix

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

if (feign.Util.isNotBlank(uri) && feign.template.UriUtils.isAbsolute(uri)) {
  throw new IllegalArgumentException("Use target() for absolute URLs: " + uri);
}

try {
  template.uri(path);
} catch (IllegalArgumentException e) {
  if ("url values must be not be absolute.".equals(e.getMessage())) {
    java.net.URI u = java.net.URI.create(path);
    template.target(u.getScheme() + "://" + u.getRawAuthority()).uri(u.getRawPath());
  } else { throw e; }
}

When it happens

Trigger: Calling template.uri("https://api.example.com/users") — UriUtils.isAbsolute detects the scheme and throws; also triggered indirectly via append/uri overloads with absolute values.

Common situations: Passing a full URL from configuration into uri() instead of target(), concatenating base URL and path then feeding the result to uri(), hardcoding absolute endpoints in templates.

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

• Invalid HTTP Method
• name is required.
• 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/34a25195650f16ee. Report an issue: GitHub.

Appendix: source

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

   *
   * @param uri to use, must be a relative uri.
   * @return a RequestTemplate for chaining.
   */
  public RequestTemplate uri(String uri) {
    return this.uri(uri, false);
  }

  /**
   * Set the uri for the request.
   *
   * @param uri to use, must be a relative uri.
   * @param append if the uri should be appended, if the uri is already set.
   * @return a RequestTemplate for chaining.
   */
  public RequestTemplate uri(String uri, boolean append) {
    /* validate and ensure that the url is always a relative one */
    if (UriUtils.isAbsolute(uri)) {
      throw new IllegalArgumentException("url values must be not be absolute.");
    }

    if (uri == null) {
      uri = "/";
    } else if ((!uri.isEmpty()
        && !uri.startsWith("/")
        && !uri.startsWith("{")
        && !uri.startsWith("?")
        && !uri.startsWith(";"))) {
      /* if the start of the url is a literal, it must begin with a slash. */
      uri = "/" + uri;
    }

    int fragmentIndex = uri.indexOf('#');
    if (fragmentIndex > -1) {
      fragment = uri.substring(fragmentIndex);
      uri = uri.substring(0, fragmentIndex);
    }

View on GitHub (pinned to e2a1e27560)