{"record":{"id":"c520cd3dbc867fd2","repo":"apache/iceberg","slug":"snowflake-max-namespace-level-is-d-got-namespace","errorCode":null,"errorMessage":"Snowflake max namespace level is %d, got namespace '%s'","messagePattern":"Snowflake max namespace level is (.+?), got namespace '(.+?)'","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"snowflake/src/main/java/org/apache/iceberg/snowflake/NamespaceHelpers.java","lineNumber":49,"sourceCode":"\n  private NamespaceHelpers() {}\n\n  /**\n   * Converts a Namespace into a SnowflakeIdentifier representing ROOT, a DATABASE, or a SCHEMA.\n   *\n   * @throws IllegalArgumentException if the namespace is not a supported depth.\n   */\n  public static SnowflakeIdentifier toSnowflakeIdentifier(Namespace namespace) {\n    switch (namespace.length()) {\n      case NAMESPACE_ROOT_LEVEL:\n        return SnowflakeIdentifier.ofRoot();\n      case NAMESPACE_DB_LEVEL:\n        return SnowflakeIdentifier.ofDatabase(namespace.level(NAMESPACE_DB_LEVEL - 1));\n      case NAMESPACE_SCHEMA_LEVEL:\n        return SnowflakeIdentifier.ofSchema(\n            namespace.level(NAMESPACE_DB_LEVEL - 1), namespace.level(NAMESPACE_SCHEMA_LEVEL - 1));\n      default:\n        throw new IllegalArgumentException(\n            String.format(\n                Locale.ROOT,\n                \"Snowflake max namespace level is %d, got namespace '%s'\",\n                MAX_NAMESPACE_DEPTH,\n                namespace));\n    }\n  }\n\n  /**\n   * Converts a TableIdentifier into a SnowflakeIdentifier of type TABLE; the identifier must have\n   * exactly the right namespace depth to represent a fully-qualified Snowflake table identifier.\n   */\n  public static SnowflakeIdentifier toSnowflakeIdentifier(TableIdentifier identifier) {\n    SnowflakeIdentifier namespaceScope = toSnowflakeIdentifier(identifier.namespace());\n    Preconditions.checkArgument(\n        namespaceScope.type() == SnowflakeIdentifier.Type.SCHEMA,\n        \"Namespace portion of '%s' must be at the SCHEMA level, got namespaceScope '%s'\",\n        identifier,","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/snowflake/src/main/java/org/apache/iceberg/snowflake/NamespaceHelpers.java#L31-L67","documentation":"NamespaceHelpers.toSnowflakeIdentifier converts an Iceberg Namespace into a Snowflake identifier. Snowflake namespaces are at most two levels (database.schema); any namespace with more levels than MAX_NAMESPACE_DEPTH has no Snowflake equivalent, so the helper throws IllegalArgumentException. This is a structural limit of Snowflake object naming, not a per-call misconfiguration.","triggerScenarios":"Calling SnowflakeCatalog.listNamespaces, loadNamespaceMetadata, or table operations with a Namespace containing 3+ levels, e.g. Namespace.of(\"db\",\"schema\",\"extra\").","commonSituations":"Translating namespaces from hierarchical catalogs (Hive, Hadoop, Nessie) that allow deep nesting into the two-level Snowflake model; programmatic namespace construction appending levels in a loop; copy-paste of multi-part identifiers from other catalogs.","solutions":["Flatten the namespace to at most two levels (database, schema) before passing it to SnowflakeCatalog","Map only the first two levels and carry the remainder elsewhere (e.g. in table name or metadata)","Use a different catalog implementation for sources with deeper namespace hierarchies"],"exampleFix":"// before\ncatalog.listNamespaces(Namespace.of(\"db\", \"schema\", \"subschema\"));\n// after\ncatalog.listNamespaces(Namespace.of(\"db\", \"schema\"));","handlingStrategy":"validation","validationCode":"if (namespace.levels().length > 2) {\n  throw new IllegalArgumentException(\n      \"Snowflake namespaces are at most 2 levels: \" + namespace);\n}","typeGuard":"boolean isSnowflakeNamespace(Namespace ns) {\n  return ns != null && ns.levels().length >= 1 && ns.levels().length <= 2;\n}","tryCatchPattern":"try {\n  catalog.loadNamespaceMetadata(namespace);\n} catch (IllegalArgumentException e) {\n  // flatten or remap the namespace before retrying\n}","preventionTips":["Cap namespace depth at 2 when bridging from hierarchical catalogs","Flatten deeper hierarchies into table names or metadata properties","Unit-test namespace converters against 3+ level inputs","Document the two-level limit at the catalog boundary"],"tags":["snowflake","namespace","identifier","validation"],"backgroundTag":"value-out-of-range","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"}