{"record":{"id":"200bf7da2e0e3ff9","repo":"OpenFeign/feign","slug":"url-request-url-couldn-t-be-parsed-into-a-u-200bf7","errorCode":null,"errorMessage":"URL '${request.url()}' couldn't be parsed into a URI","messagePattern":"URL '(.+?)' couldn't be parsed into a URI","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"httpclient/src/main/java/feign/httpclient/ApacheHttpClient.java","lineNumber":82,"sourceCode":"  private static final String ACCEPT_HEADER_NAME = \"Accept\";\n\n  private final HttpClient client;\n\n  public ApacheHttpClient() {\n    this(HttpClientBuilder.create().build());\n  }\n\n  public ApacheHttpClient(HttpClient client) {\n    this.client = client;\n  }\n\n  @Override\n  public Response execute(Request request, Request.Options options) throws IOException {\n    HttpUriRequest httpUriRequest;\n    try {\n      httpUriRequest = toHttpUriRequest(request, options);\n    } catch (URISyntaxException e) {\n      throw new IOException(\"URL '\" + request.url() + \"' couldn't be parsed into a URI\", e);\n    }\n    HttpResponse httpResponse = client.execute(httpUriRequest);\n    return toFeignResponse(httpResponse, request);\n  }\n\n  HttpUriRequest toHttpUriRequest(Request request, Request.Options options)\n      throws URISyntaxException {\n    RequestBuilder requestBuilder = RequestBuilder.create(request.httpMethod().name());\n\n    // per request timeouts\n    RequestConfig requestConfig =\n        (client instanceof Configurable\n                ? RequestConfig.copy(((Configurable) client).getConfig())\n                : RequestConfig.custom())\n            .setConnectTimeout(options.connectTimeoutMillis())\n            .setSocketTimeout(options.readTimeoutMillis())\n            .setRedirectsEnabled(options.isFollowRedirects())\n            .build();","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/OpenFeign/feign/blob/e2a1e27560a1e68840c34f031afca88b36096e30/httpclient/src/main/java/feign/httpclient/ApacheHttpClient.java#L64-L100","documentation":"ApacheHttpClient.execute converts the Feign Request URL into an HttpUriRequest; if the URL string cannot be parsed into a java.net.URI (URISyntaxException), it is rethrown as an IOException with the offending URL in the message. Feign URLs are templates that should be valid URIs, so this indicates malformed URL construction.","triggerScenarios":"Calling a Feign client where the resolved target URL contains illegal characters (unencoded spaces, '{', '}', '|', non-ASCII characters), an empty path component bug, or a path/query parameter expanded with raw special characters not URL-encoded by the encoder.","commonSituations":"Passing path variables containing spaces or unencoded reserved characters; building target URLs by string concatenation instead of RequestTemplate; hosting config with a typo (double slashes, missing scheme handled upstream); migrating to ApacheHttpClient which is stricter than other clients.","solutions":["Log/inspect the URL in the message and fix the illegal character at its source.","URL-encode path and query parameter values before passing them (or rely on Feign's @Param expansion with proper encoding).","Fix the @RequestLine/URL template so placeholders are expanded, not left with literal braces.","Validate the base URL/host configuration for stray whitespace, double slashes, or bad characters."],"exampleFix":"// before\nString name = \"john doe\";\napi.getUser(name); // GET /users/john doe -> URISyntaxException\n// after\nString name = URLEncoder.encode(\"john doe\", StandardCharsets.UTF_8);\napi.getUser(name); // GET /users/john%20doe","handlingStrategy":"validation","validationCode":"static boolean isUriSafe(String url) {\n  try { new java.net.URI(url); return true; } catch (java.net.URISyntaxException e) { return false; }\n}\n// run before building the Feign request; encode values with URLEncoder if false","typeGuard":null,"tryCatchPattern":"try {\n  response = feignClient.call(param);\n} catch (java.io.IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"couldn't be parsed into a URI\")) {\n    throw new IllegalArgumentException(\"Bad URL built from param, encode it first\", e);\n  }\n  throw e;\n}","preventionTips":["URL-encode all path and query parameter values","Never build URLs via raw string concatenation for Feign targets","Trim whitespace from configured base URLs","Avoid characters like space, '{', '}', '|' in parameter values"],"tags":["url","uri-syntax","http-client","encoding"],"backgroundTag":"invalid-url-format","analyzedSha":"e2a1e27560a1e68840c34f031afca88b36096e30","analyzedAt":"2026-09-10T12:37:37.238Z","contentChangedAt":"2026-09-10T12:37:37.238Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}