{"record":{"id":"481fb32dc0b3a7aa","repo":"apache/iceberg","slug":"uri-doesn-t-end-with-the-version-s-please-confi","errorCode":null,"errorMessage":"URI doesn't end with the version: %s. Please configure `client-api-version` in the catalog properties explicitly.","messagePattern":"URI doesn't end with the version: (.+?)\\. Please configure `client-api-version` in the catalog properties explicitly\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"nessie/src/main/java/org/apache/iceberg/nessie/NessieCatalog.java","lineNumber":147,"sourceCode":"    initialize(\n        name,\n        new NessieIcebergClient(api, requestedRef, requestedHash, catalogOptions),\n        CatalogUtil.loadFileIO(fileIOImpl, options, config),\n        catalogOptions);\n  }\n\n  private static String inferVersionFromURI(String uri) {\n    if (uri == null) {\n      throw new IllegalArgumentException(\"URI is not specified in the catalog properties\");\n    }\n\n    // match for uri ending with /v1, /v2 etc\n    Pattern pattern = Pattern.compile(\"/v(\\\\d+)$\");\n    Matcher matcher = pattern.matcher(uri);\n    if (matcher.find()) {\n      return matcher.group(1);\n    } else {\n      throw new IllegalArgumentException(\n          String.format(\n              \"URI doesn't end with the version: %s. \"\n                  + \"Please configure `client-api-version` in the catalog properties explicitly.\",\n              uri));\n    }\n  }\n\n  /**\n   * An alternative way to initialize the catalog using a pre-configured {@link NessieIcebergClient}\n   * and {@link FileIO} instance.\n   *\n   * @param name The name of the catalog, defaults to \"nessie\" if <code>null</code>\n   * @param client The pre-configured {@link NessieIcebergClient} instance to use\n   * @param fileIO The {@link FileIO} instance to use\n   * @param catalogOptions The catalog options to use\n   */\n  @SuppressWarnings(\"checkstyle:HiddenField\")\n  public void initialize(","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/nessie/src/main/java/org/apache/iceberg/nessie/NessieCatalog.java#L129-L165","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set 'client-api-version' to \"1\" or \"2\" explicitly in the catalog properties.","Or change the uri to end with the version segment, e.g. \"http://nessie:19120/api/v2\".","Confirm which API version your Nessie server exposes (v1 vs v2) and encode that in the URI."],"exampleFix":"// before\nproperties.put(\"uri\", \"http://nessie:19120\");\n// after\nproperties.put(\"uri\", \"http://nessie:19120\");\nproperties.put(\"client-api-version\", \"2\");","handlingStrategy":"validation","validationCode":"String uri = properties.get(\"uri\");\nif (uri != null && properties.get(\"client-api-version\") == null && !uri.matches(\".*/v\\\\d+$\")) {\n  throw new IllegalArgumentException(\"uri must end with /v1 or /v2 or set client-api-version explicitly\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(name, props, conf);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"URI doesn't end with the version\")) {\n    props.put(\"client-api-version\", \"2\");\n    catalog.initialize(name, props, conf);\n  } else throw e;\n}","preventionTips":["Prefer URIs that include the version segment, e.g. http://host:19120/api/v2","When using proxies or shortened URLs, always set client-api-version explicitly","Test catalog initialization in CI against the same URI shape used in production"],"tags":["nessie","catalog","config","uri","version-detection"],"backgroundTag":"invalid-url-format","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}