apache/iceberg · error · RESTException

Failed to create request URI from base

Error message

Failed to create request URI from base %s

What it means

The HTTPClient.Builder.uri(String) method parses the configured base URI after stripping a trailing slash. If URI.create rejects the string (IllegalArgumentException), it is rethrown as RESTException with this message. It means the catalog base URI string is not a syntactically valid URI.

Solutions

1. Print and inspect the base URI string; trim whitespace and newlines around it.
2. Percent-encode special characters (e.g. spaces as %20) or remove them from the URI.
3. Validate the URI with java.net.URI.create in a quick test before configuring the client.
4. Fix the source of the value (env var, catalog config, properties file) that embeds invalid characters.

Example fix

// before
String baseUri = System.getenv("CATALOG_URI"); // "http://rest:8181 "
builder.uri(baseUri);
// after
builder.uri(System.getenv("CATALOG_URI").trim());

String baseUri = config.get("uri").trim();
URI.create(RESTUtil.stripTrailingSlash(baseUri)); // throws early with a clear message
builder.uri(baseUri);

try {
  builder.uri(baseUri);
} catch (RESTException e) {
  if (e.getMessage().startsWith("Failed to create request URI from base")) {
    // log baseUri repr and fix config source
  }
  throw e;
}

When it happens

Trigger: Calling HTTPClient.Builder.uri(String) (directly or via REST catalog catalog initialization) with a malformed base URI — e.g. containing spaces, unencoded special characters like unescaped '|', or a bad scheme.

Common situations: Catalog URI read from an environment variable or config file containing a trailing space or newline; unencoded characters in the URL; scheme typo like 'http:/catalog' (single slash); quotes accidentally included in the config value.

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

• Received a request with a relative path and no base URI
• Cannot assume role to sign REST requests because is not…
• Cannot initialize AuthManager implementation
• Failed to create request URI from base
• Invalid idempotency lifetime:

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/rest/HTTPClient.java:519

  public static class Builder {
    private final Map<String, String> properties;
    private final Map<String, String> baseHeaders = Maps.newHashMap();
    private URI uri;
    private ObjectMapper mapper = RESTObjectMapper.mapper();
    private HttpHost proxy;
    private CredentialsProvider proxyCredentialsProvider;
    private AuthSession authSession;

    private Builder(Map<String, String> properties) {
      this.properties = properties;
    }

    public Builder uri(String baseUri) {
      Preconditions.checkNotNull(baseUri, "Invalid uri for http client: null");
      try {
        this.uri = URI.create(RESTUtil.stripTrailingSlash(baseUri));
      } catch (IllegalArgumentException e) {
        throw new RESTException(e, "Failed to create request URI from base %s", baseUri);
      }
      return this;
    }

    public Builder uri(URI baseUri) {
      Preconditions.checkNotNull(baseUri, "Invalid uri for http client: null");
      this.uri = baseUri;
      return this;
    }

    public Builder withProxy(String hostname, int port) {
      Preconditions.checkNotNull(hostname, "Invalid hostname for http client proxy: null");
      this.proxy = new HttpHost(hostname, port);
      return this;
    }

    public Builder withProxyCredentialsProvider(CredentialsProvider credentialsProvider) {
      Preconditions.checkNotNull(

View on GitHub (pinned to 86d9c8fc54)