apache/iceberg · error · IllegalArgumentException

URI is not specified in the catalog properties

Error message

URI is not specified in the catalog properties

What it means

When 'client-api-version' is not set, NessieCatalog tries to infer the Nessie client API version from the catalog's 'uri' via inferVersionFromURI. If the URI (warehouse-less endpoint property) is null — i.e. no URI was supplied at all — it throws this IllegalArgumentException.

Source

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

        api = nessieClientBuilder.build(NessieApiV2.class);
        break;
      default:
        throw new IllegalArgumentException(
            String.format(
                "Unsupported %s: %s. Can only be 1 or 2",
                removePrefix.apply(NessieUtil.CLIENT_API_VERSION), apiVersion));
    }

    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}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Add the 'uri' property pointing at the Nessie server, e.g. "http://nessie:19120/api/v2".
2. Alternatively set 'client-api-version' explicitly to "1" or "2" — though you still normally need the uri to connect.
3. Double-check the property key is exactly 'uri' (no typos/extra whitespace).

Example fix

// before
Map<String, String> props = Map.of("ref", "main");
// after
Map<String, String> props = Map.of("uri", "http://nessie:19120/api/v2", "ref", "main");

if (properties.get("uri") == null && properties.get("client-api-version") == null) {
  throw new IllegalArgumentException("Nessie catalog requires 'uri' (or explicit client-api-version with endpoint)");
}

try {
  catalog.initialize(name, props, conf);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("URI is not specified")) {
    props.put("uri", "http://nessie:19120/api/v2");
    catalog.initialize(name, props, conf);
  } else throw e;
}

When it happens

Trigger: Initializing NessieCatalog without a 'uri' entry in the catalog properties and without 'client-api-version' set, so there is nothing to infer the API version from.

Common situations: Forgetting the 'uri' key when assembling the catalog config map; renaming the property key by mistake; building options programmatically and omitting the endpoint.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• URI doesn't end with the version: %s. Please configure `clie
• 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/23c3449c004905ae. Report an issue: GitHub.