{"record":{"id":"9acf8c2f5bd5d390","repo":"apache/iceberg","slug":"unsupported-s-s-can-only-be-1-or-2","errorCode":null,"errorMessage":"Unsupported %s: %s. Can only be 1 or 2","messagePattern":"Unsupported (.+?): (.+?)\\. Can only be 1 or 2","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"nessie/src/main/java/org/apache/iceberg/nessie/NessieCatalog.java","lineNumber":123,"sourceCode":"            .fallbackTo(x -> options.get(removePrefix.apply(x)));\n    NessieClientBuilder nessieClientBuilder =\n        NessieClientBuilder.createClientBuilderFromSystemSettings(configSource);\n    // default version is inferred by uri.\n    String apiVersion = options.get(removePrefix.apply(NessieUtil.CLIENT_API_VERSION));\n    if (apiVersion == null) {\n      apiVersion = inferVersionFromURI(options.get(CatalogProperties.URI));\n    }\n\n    NessieApiV1 api;\n    switch (apiVersion) {\n      case \"1\":\n        api = nessieClientBuilder.build(NessieApiV1.class);\n        break;\n      case \"2\":\n        api = nessieClientBuilder.build(NessieApiV2.class);\n        break;\n      default:\n        throw new IllegalArgumentException(\n            String.format(\n                \"Unsupported %s: %s. Can only be 1 or 2\",\n                removePrefix.apply(NessieUtil.CLIENT_API_VERSION), apiVersion));\n    }\n\n    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","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/nessie/src/main/java/org/apache/iceberg/nessie/NessieCatalog.java#L105-L141","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set the property to exactly \"1\" or \"2\": catalog.setProperty(\"client-api-version\", \"2\").","Remove 'client-api-version' entirely so the version is inferred from the URI suffix (/v1, /v2).","Check the Nessie server version: only API versions 1 and 2 are supported by this client."],"exampleFix":"// before\nproperties.put(\"client-api-version\", \"v2\");\n// after\nproperties.put(\"client-api-version\", \"2\");","handlingStrategy":"validation","validationCode":"String v = properties.get(\"client-api-version\");\nif (v != null && !v.equals(\"1\") && !v.equals(\"2\")) {\n  throw new IllegalArgumentException(\"client-api-version must be '1' or '2', got: \" + v);\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.initialize(name, props, conf);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"client-api-version\") || e.getMessage().contains(\"Unsupported\")) {\n    props.put(\"client-api-version\", \"2\");\n    catalog.initialize(name, props, conf);\n  } else throw e;\n}","preventionTips":["Use the bare strings \"1\" or \"2\" — never \"v1\"/\"v2\"","Omit client-api-version and let NessieCatalog infer it from a URI ending in /v1 or /v2","Keep catalog property values in one reviewed config file/version control"],"tags":["nessie","catalog","config","enum"],"backgroundTag":"invalid-enum-value","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"}