apache/iceberg · error · RESTException

Received a request with a relative path and no base URI

Error message

Received a request with a relative path and no base URI: %s

What it means

HTTPRequest validates itself before sending a REST request. A request whose path is relative (not starting with http:// or https://) must be resolved against a base URI supplied by the catalog configuration; if no base URI is set and the path itself is not absolute, the request cannot be routed, so a RESTException is thrown during the check().

Solutions

1. Set the 'uri' property in the REST catalog configuration to an absolute HTTP(S) endpoint
2. Use an absolute URL as the request path if no base URI applies
3. Verify the config map/properties actually contain the base URI key (watch for typos)
4. If constructing HTTPRequest directly, pass a non-null baseUri

Example fix

// before
catalog = CatalogLoader.load("prod", ImmutableMap.of("type", "rest"), hadoopConf);
// after
catalog = CatalogLoader.load("prod", ImmutableMap.of("type", "rest", "uri", "https://rest.catalog.example.com"), hadoopConf);

String uri = conf.get(CatalogProperties.URI);
if (uri == null || !(uri.startsWith("http://") || uri.startsWith("https://"))) {
  throw new IllegalArgumentException("REST catalog requires an absolute http(s) 'uri' property");
}

boolean hasUsableTarget(String path, java.net.URI baseUri) {
  return baseUri != null || path.startsWith("http://") || path.startsWith("https://");
}

try {
  return client.post(path, body, Type.class, headers, handler);
} catch (RESTException e) {
  if (e.getMessage().contains("relative path and no base URI")) {
    throw new IllegalStateException("Catalog 'uri' is not configured", e);
  }
  throw e;
}

When it happens

Trigger: Calling RESTClient/HTTPRequest with a relative path like 'v1/namespaces' while the catalog's uri property is null or unset; constructing an HTTPRequest manually without a base URI; misconfigured REST catalog where 'uri' is missing from catalog properties.

Common situations: Deploying a Spark/Flink job with an incomplete catalog config (missing warehouse/uri), building a custom REST catalog client programmatically and forgetting to set the base endpoint, or typos in configuration keys so the URI never loads.

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
• 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/abde74c7c02bf93d. Report an issue: GitHub.

Appendix: source

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

  /**
   * Returns the {@link ObjectMapper} to use for encoding the request body. The default is {@link
   * RESTObjectMapper#mapper()}.
   */
  @Value.Default
  default ObjectMapper mapper() {
    return RESTObjectMapper.mapper();
  }

  @Value.Check
  default void check() {
    if (path().startsWith("/")) {
      throw new RESTException(
          "Received a malformed path for a REST request: %s. Paths should not start with /",
          path());
    }

    if (baseUri() == null && !hasAbsolutePath()) {
      throw new RESTException(
          "Received a request with a relative path and no base URI: %s", path());
    }
  }

  private boolean hasAbsolutePath() {
    return path().startsWith("https://") || path().startsWith("http://");
  }
}

View on GitHub (pinned to 86d9c8fc54)