What causes "Target is not a valid URI." in OpenFeign/feign?

Percent-encode illegal characters or remove them from the target URL

OpenFeign/feign · error · IllegalArgumentException

Target is not a valid URI.

Error message

Target is not a valid URI.

What it means

RequestTemplate.target(String) parses the target into a URI. If parsing fails (malformed URI, illegal characters, bad port, etc.), the caught IllegalArgumentException is rethrown as 'Target is not a valid URI.' with the original cause attached.

Solutions

Percent-encode illegal characters or remove them from the target URL
Validate the base URL with new URI(url) or UriUtils before configuring Feign
Check the cause (iae.getCause()) in logs for the exact parse failure (bad port, illegal char)
Fix the environment/config value supplying the target

Example fix

// before
template.target("https://api.example.com/a b");
// after
template.target("https://api.example.com/a%20b");

Defensive patterns

Strategy: try-catch

Validate before calling

try {
  new java.net.URI(baseUrl); // throws if invalid
} catch (java.net.URISyntaxException e) {
  throw new IllegalArgumentException("Invalid configured base URL: " + baseUrl, e);
}

Try / catch

try {
  template.target(baseUrl);
} catch (IllegalArgumentException e) {
  if ("Target is not a valid URI.".equals(e.getMessage())) {
    LOGGER.error("Malformed target '{}', cause: {}", baseUrl, e.getCause());
    throw new ConfigurationException("Fix base URL encoding: " + baseUrl, e);
  }
  throw e;
}

Prevention

Percent-encode spaces and non-ASCII characters in URLs
Validate base URLs with new URI(...) before configuring Feign
Log e.getCause() to identify the exact URI parse problem
Avoid hand-built URLs from concatenation; use URI builders

When it happens

Trigger: Passing a syntactically invalid target such as 'https://exa mple.com', 'http://host:notaport/', or a URL with unescaped illegal characters to target(); thrown during insert/create/apply flows.

Common situations: Unencoded spaces or non-ASCII characters in configured base URLs, corrupted env/config values, ports or IPv6 literals formatted incorrectly.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

      /* 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();
      if (targetUri.getFragment() != null) {
        this.fragment = "#" + targetUri.getFragment();
      }
    } catch (IllegalArgumentException iae) {
      /* the uri provided is not a valid one, we can't continue */
      throw new IllegalArgumentException("Target is not a valid URI.", iae);
    }
    return this;
  }

  /**
   * The URL for the request. If the template has not been resolved, the url will represent a uri
   * template.
   *
   * @return the url
   */
  public String url() {

    /* build the fully qualified url with all query parameters */
    StringBuilder url = new StringBuilder(this.path());
    if (!this.queries.isEmpty()) {
      url.append(this.queryLine());
    }
    if (fragment != null) {

View on GitHub (pinned to e2a1e27560)