apache/iceberg · error · RESTException

Received a malformed path for a REST request

Error message

Received a malformed path for a REST request: %s. Paths should not start with /

What it means

HTTPRequest's @Value.Check validates the request at construction. A path starting with '/' is rejected with this RESTException because the client joins the path onto the base URI itself; a leading slash would produce a malformed or wrong URL. The check also rejects relative paths when no base URI is configured.

Solutions

Remove the leading '/' from the request path (paths must be relative, e.g. "v1/namespaces").
Strip leading slashes programmatically when paths are built from variables or user input.
Set the client's base URI via HTTPClient.Builder.uri(...) when using relative paths.
Use RESTUtil.stripLeadingSlash or equivalent before constructing the request.

Example fix

// before
HTTPRequest.get("/v1/namespaces");
// after
HTTPRequest.get(RESTUtil.stripLeadingSlash("/v1/namespaces")); // "v1/namespaces"

Defensive patterns

Strategy: validation

Validate before calling

String p = rawPath;
if (p.startsWith("/")) p = p.substring(1);
Preconditions.checkArgument(!p.startsWith("/"), "path must be relative");
HTTPRequest.get(p);

Try / catch

try {
  HTTPRequest.get(path);
} catch (RESTException e) {
  if (e.getMessage().contains("should not start with /")) {
    // strip the leading slash and rebuild the request
  }
  throw e;
}

Prevention

Never start request paths with '/'; strip it when paths come from variables.
Configure the client base URI and keep request paths relative.
Add a unit test that builds every request path your code uses.

When it happens

Trigger: Calling HTTPRequest.post("/v1/namespaces") or .get("/tables/x") — any path with a leading slash; also building a request without a base URI set while the path is not absolute.

Common situations: Copy-pasting a full URL path (with leading slash) from API docs into a client request; building paths by string concatenation where an earlier part already ends in '/'; using HTTPRequest without configuring the client's base URI.

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.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

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

        throw new RESTException(e, "Failed to encode request body: %s", body);
      }
    }
    return null;
  }

  /**
   * 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)