apache/iceberg · error · IllegalArgumentException

URI doesn't end with the version: %s. Please configure `clie

Error message

URI doesn't end with the version: %s. Please configure `client-api-version` in the catalog properties explicitly.

What it means

NessieCatalog infers the client API version by matching a '/v<digits>' suffix on the catalog URI. If 'client-api-version' is unset and the URI doesn't end with /v1 or /v2 (e.g. no version path segment), inferVersionFromURI throws this IllegalArgumentException asking you to configure client-api-version explicitly.

Source

Thrown at nessie/src/main/java/org/apache/iceberg/nessie/NessieCatalog.java:147

    initialize(
        name,
        new NessieIcebergClient(api, requestedRef, requestedHash, catalogOptions),
        CatalogUtil.loadFileIO(fileIOImpl, options, config),
        catalogOptions);
  }

  private static String inferVersionFromURI(String uri) {
    if (uri == null) {
      throw new IllegalArgumentException("URI is not specified in the catalog properties");
    }

    // match for uri ending with /v1, /v2 etc
    Pattern pattern = Pattern.compile("/v(\\d+)$");
    Matcher matcher = pattern.matcher(uri);
    if (matcher.find()) {
      return matcher.group(1);
    } else {
      throw new IllegalArgumentException(
          String.format(
              "URI doesn't end with the version: %s. "
                  + "Please configure `client-api-version` in the catalog properties explicitly.",
              uri));
    }
  }

  /**
   * An alternative way to initialize the catalog using a pre-configured {@link NessieIcebergClient}
   * and {@link FileIO} instance.
   *
   * @param name The name of the catalog, defaults to "nessie" if <code>null</code>
   * @param client The pre-configured {@link NessieIcebergClient} instance to use
   * @param fileIO The {@link FileIO} instance to use
   * @param catalogOptions The catalog options to use
   */
  @SuppressWarnings("checkstyle:HiddenField")
  public void initialize(

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set 'client-api-version' to "1" or "2" explicitly in the catalog properties.
2. Or change the uri to end with the version segment, e.g. "http://nessie:19120/api/v2".
3. Confirm which API version your Nessie server exposes (v1 vs v2) and encode that in the URI.

Example fix

// before
properties.put("uri", "http://nessie:19120");
// after
properties.put("uri", "http://nessie:19120");
properties.put("client-api-version", "2");

String uri = properties.get("uri");
if (uri != null && properties.get("client-api-version") == null && !uri.matches(".*/v\\d+$")) {
  throw new IllegalArgumentException("uri must end with /v1 or /v2 or set client-api-version explicitly");
}

try {
  catalog.initialize(name, props, conf);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("URI doesn't end with the version")) {
    props.put("client-api-version", "2");
    catalog.initialize(name, props, conf);
  } else throw e;
}

When it happens

Trigger: Initializing NessieCatalog with a 'uri' like "http://nessie:19120" or "http://nessie:19120/api" (no trailing /v1 or /v2) and no 'client-api-version' property.

Common situations: Pointing at an older Nessie deployment whose endpoint lacks the version segment; proxy/gateway URLs that strip path suffixes; copy-pasted URLs missing the /api/v1 part.

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

• URI is not specified in the catalog properties
• Unsupported %s: %s. Can only be 1 or 2
• Parameter 'warehouse' not set, Nessie can't store data.
• Cannot load namespace '%s': ref '%s' is no longer valid.
• Cannot update properties on namespace '%s': %s

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