{"record":{"id":"1f6e616e727349dc","repo":"apache/iceberg","slug":"listnamespaces-must-be-at-either-root-or-database","errorCode":null,"errorMessage":"listNamespaces must be at either ROOT or DATABASE level; got %s from namespace %s","messagePattern":"listNamespaces must be at either ROOT or DATABASE level; got (.+?) from namespace (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"snowflake/src/main/java/org/apache/iceberg/snowflake/SnowflakeCatalog.java","lineNumber":189,"sourceCode":"  @Override\n  public void createNamespace(Namespace namespace, Map<String, String> metadata) {\n    throw new UnsupportedOperationException(\n        \"SnowflakeCatalog does not currently support createNamespace\");\n  }\n\n  @Override\n  public List<Namespace> listNamespaces(Namespace namespace) {\n    SnowflakeIdentifier scope = NamespaceHelpers.toSnowflakeIdentifier(namespace);\n    List<SnowflakeIdentifier> results;\n    switch (scope.type()) {\n      case ROOT:\n        results = snowflakeClient.listDatabases();\n        break;\n      case DATABASE:\n        results = snowflakeClient.listSchemas(scope);\n        break;\n      default:\n        throw new IllegalArgumentException(\n            String.format(\n                \"listNamespaces must be at either ROOT or DATABASE level; got %s from namespace %s\",\n                scope, namespace));\n    }\n\n    return results.stream().map(NamespaceHelpers::toIcebergNamespace).collect(Collectors.toList());\n  }\n\n  @Override\n  public Map<String, String> loadNamespaceMetadata(Namespace namespace)\n      throws NoSuchNamespaceException {\n    SnowflakeIdentifier id = NamespaceHelpers.toSnowflakeIdentifier(namespace);\n    boolean namespaceExists;\n    switch (id.type()) {\n      case DATABASE:\n        namespaceExists = snowflakeClient.databaseExists(id);\n        break;\n      case SCHEMA:","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/snowflake/src/main/java/org/apache/iceberg/snowflake/SnowflakeCatalog.java#L171-L207","documentation":"SnowflakeCatalog.listNamespaces can only enumerate databases (ROOT scope) or schemas (DATABASE scope). A namespace resolving to SCHEMA or TABLE scope reaches the default branch and throws IllegalArgumentException, because Snowflake has no third namespace level to list.","triggerScenarios":"Calling listNamespaces(Namespace.of(\"db\",\"schema\")) — schema-level listing is not supported; the input namespace must be empty (ROOT) or exactly one level (DATABASE).","commonSituations":"Generic catalog explorers that recursively list nested namespaces; code ported from Hive/Hadoop catalogs listing children of a schema; tooling iterating all namespace levels.","solutions":["Only call listNamespaces with Namespace.empty() or a single-level (database) namespace","Treat a two-level namespace as a leaf: stop recursion at schema level","Check namespace.levels().length <= 1 before invoking listNamespaces"],"exampleFix":"// before\ncatalog.listNamespaces(Namespace.of(\"db\", \"schema\")); // throws\n// after\nif (namespace.levels().length <= 1) {\n  catalog.listNamespaces(namespace);\n}","handlingStrategy":"validation","validationCode":"if (namespace.levels().length > 1) {\n  throw new IllegalArgumentException(\n      \"listNamespaces supports only ROOT or DATABASE level: \" + namespace);\n}","typeGuard":"boolean isListableNamespace(Namespace ns) {\n  return ns != null && ns.levels().length <= 1;\n}","tryCatchPattern":"try {\n  catalog.listNamespaces(namespace);\n} catch (IllegalArgumentException e) {\n  // stop recursion: schema-level namespaces have no children here\n}","preventionTips":["Limit namespace recursion depth to 1 for SnowflakeCatalog","Treat schema-level namespaces as leaves in generic explorers","Test recursive catalog walkers against SnowflakeCatalog","Check namespace level before each listNamespaces call"],"tags":["snowflake","namespace","validation","unsupported-operation"],"backgroundTag":"invalid-argument-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"}