apache/iceberg · error · RESTException

Failed to create request URI from base

Error message

Failed to create request URI from base %s, params %s

What it means

HTTPRequest.requestUri builds the final request URI from the full path plus query parameters using URIBuilder. If URIBuilder.build() throws URISyntaxException (the path or parameter values are not valid URI components), the client throws RESTException with this message. It is raised by uri(), request(), and requestUriSuccess() whenever the request's path/query cannot be assembled.

Solutions

1. URL-encode path segments with RESTUtil.encodeString (or URLEncoder) before interpolating identifiers into paths.
2. Pass query parameters via the request's queryParameters() map instead of concatenating '?a=b' into the path.
3. Strip or encode illegal characters from the base URI/path configuration.
4. Print fullPath and queryParameters() from the message to spot the offending segment.

Example fix

// before
String path = "v1/namespaces/" + namespace + "/tables"; // namespace has a space
// after
String path = "v1/namespaces/" + RESTUtil.encodeString(namespace) + "/tables";

String encoded = RESTUtil.encodeString(namespace);
Preconditions.checkArgument(!fullPath.contains(" "), "path contains a space: %s", fullPath);

try {
  HTTPRequest req = HTTPRequest.get(path);
} catch (RESTException e) {
  if (e.getMessage().startsWith("Failed to create request URI")) {
    // encode path segments / move values into queryParameters()
  }
  throw e;
}

When it happens

Trigger: Building a request whose path() contains characters illegal in a URI (spaces, unencoded braces/brackets), or query parameters with values needing encoding passed through a path that already broke URI syntax; e.g. HTTPRequest.post("tables/ ns/table") with queryParameters.

Common situations: Identifiers (namespace/table names) containing spaces or unicode interpolated into the path without URL-encoding; custom REST client code building paths with raw strings; config-supplied prefix paths containing invalid characters.

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

• Failed to create request URI from base
• Received a malformed path for a REST request
• Received a request with a relative path and no base URI
• Byte stream split encoding is not supported for type " +…
• Cannot assume role to sign REST requests because is not…

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/2667044009ea790b. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/HTTPRequest.java:72

   * parameters. It cannot be modified directly.
   */
  @Value.Lazy
  default URI requestUri() {
    String fullPath;
    if (hasAbsolutePath()) {
      // if path is an absolute URI, use it as is
      fullPath = path();
    } else {
      String baseUri = RESTUtil.stripTrailingSlash(baseUri().toString());
      fullPath = RESTUtil.stripTrailingSlash(String.format("%s/%s", baseUri, path()));
    }

    try {
      URIBuilder builder = new URIBuilder(fullPath);
      queryParameters().forEach(builder::addParameter);
      return builder.build();
    } catch (URISyntaxException e) {
      throw new RESTException(
          "Failed to create request URI from base %s, params %s", fullPath, queryParameters());
    }
  }

  /** Returns the HTTP method of this request. */
  HTTPMethod method();

  /** Returns the path of this request. */
  String path();

  /** Returns the query parameters of this request. */
  Map<String, String> queryParameters();

  /** Returns the headers of this request. */
  @Value.Default
  default HTTPHeaders headers() {
    return HTTPHeaders.EMPTY;
  }

View on GitHub (pinned to 86d9c8fc54)