apache/iceberg · error · IllegalArgumentException

Unsupported %s: %s. Can only be 1 or 2

Error message

Unsupported %s: %s. Can only be 1 or 2

What it means

NessieCatalog.initialize reads the catalog property 'client-api-version' to decide whether to build a NessieApiV1 or NessieApiV2 client. If the property is set to anything other than "1" or "2" it throws this IllegalArgumentException during catalog initialization.

Source

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

            .fallbackTo(x -> options.get(removePrefix.apply(x)));
    NessieClientBuilder nessieClientBuilder =
        NessieClientBuilder.createClientBuilderFromSystemSettings(configSource);
    // default version is inferred by uri.
    String apiVersion = options.get(removePrefix.apply(NessieUtil.CLIENT_API_VERSION));
    if (apiVersion == null) {
      apiVersion = inferVersionFromURI(options.get(CatalogProperties.URI));
    }

    NessieApiV1 api;
    switch (apiVersion) {
      case "1":
        api = nessieClientBuilder.build(NessieApiV1.class);
        break;
      case "2":
        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

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set the property to exactly "1" or "2": catalog.setProperty("client-api-version", "2").
2. Remove 'client-api-version' entirely so the version is inferred from the URI suffix (/v1, /v2).
3. Check the Nessie server version: only API versions 1 and 2 are supported by this client.

Example fix

// before
properties.put("client-api-version", "v2");
// after
properties.put("client-api-version", "2");

String v = properties.get("client-api-version");
if (v != null && !v.equals("1") && !v.equals("2")) {
  throw new IllegalArgumentException("client-api-version must be '1' or '2', got: " + v);
}

try {
  catalog.initialize(name, props, conf);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("client-api-version") || e.getMessage().contains("Unsupported")) {
    props.put("client-api-version", "2");
    catalog.initialize(name, props, conf);
  } else throw e;
}

When it happens

Trigger: Setting catalog property 'client-api-version' to a value like "3", "v1", "v2", "0", or a typo string, then calling NessieCatalog.initialize(name, options, conf).

Common situations: Typo in the catalog config (e.g. 'v2' instead of '2'); misreading docs and thinking 'v1'/'v2' are valid; assuming newer server versions auto-map to version 3.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• URI is not specified in the catalog properties
• URI doesn't end with the version: %s. Please configure `clie
• Parameter 'warehouse' not set, Nessie can't store data.
• Invalid rewrite job order name: %s
• Unknown catalog type:

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