apache/iceberg · error · IllegalArgumentException

Snowflake max namespace level is %d, got namespace '%s'

Error message

Snowflake max namespace level is %d, got namespace '%s'

What it means

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.

Source

Thrown at snowflake/src/main/java/org/apache/iceberg/snowflake/NamespaceHelpers.java:49

  private NamespaceHelpers() {}

  /**
   * Converts a Namespace into a SnowflakeIdentifier representing ROOT, a DATABASE, or a SCHEMA.
   *
   * @throws IllegalArgumentException if the namespace is not a supported depth.
   */
  public static SnowflakeIdentifier toSnowflakeIdentifier(Namespace namespace) {
    switch (namespace.length()) {
      case NAMESPACE_ROOT_LEVEL:
        return SnowflakeIdentifier.ofRoot();
      case NAMESPACE_DB_LEVEL:
        return SnowflakeIdentifier.ofDatabase(namespace.level(NAMESPACE_DB_LEVEL - 1));
      case NAMESPACE_SCHEMA_LEVEL:
        return SnowflakeIdentifier.ofSchema(
            namespace.level(NAMESPACE_DB_LEVEL - 1), namespace.level(NAMESPACE_SCHEMA_LEVEL - 1));
      default:
        throw new IllegalArgumentException(
            String.format(
                Locale.ROOT,
                "Snowflake max namespace level is %d, got namespace '%s'",
                MAX_NAMESPACE_DEPTH,
                namespace));
    }
  }

  /**
   * Converts a TableIdentifier into a SnowflakeIdentifier of type TABLE; the identifier must have
   * exactly the right namespace depth to represent a fully-qualified Snowflake table identifier.
   */
  public static SnowflakeIdentifier toSnowflakeIdentifier(TableIdentifier identifier) {
    SnowflakeIdentifier namespaceScope = toSnowflakeIdentifier(identifier.namespace());
    Preconditions.checkArgument(
        namespaceScope.type() == SnowflakeIdentifier.Type.SCHEMA,
        "Namespace portion of '%s' must be at the SCHEMA level, got namespaceScope '%s'",
        identifier,

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Flatten the namespace to at most two levels (database, schema) before passing it to SnowflakeCatalog
2. Map only the first two levels and carry the remainder elsewhere (e.g. in table name or metadata)
3. Use a different catalog implementation for sources with deeper namespace hierarchies

Example fix

// before
catalog.listNamespaces(Namespace.of("db", "schema", "subschema"));
// after
catalog.listNamespaces(Namespace.of("db", "schema"));

if (namespace.levels().length > 2) {
  throw new IllegalArgumentException(
      "Snowflake namespaces are at most 2 levels: " + namespace);
}

boolean isSnowflakeNamespace(Namespace ns) {
  return ns != null && ns.levels().length >= 1 && ns.levels().length <= 2;
}

try {
  catalog.loadNamespaceMetadata(namespace);
} catch (IllegalArgumentException e) {
  // flatten or remap the namespace before retrying
}

When it happens

Trigger: Calling SnowflakeCatalog.listNamespaces, loadNamespaceMetadata, or table operations with a Namespace containing 3+ levels, e.g. Namespace.of("db","schema","extra").

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid table identifier: %s
• Cannot convert identifier '%s' to Namespace
• listNamespaces must be at either ROOT or DATABASE level; got
• loadNamespaceMetadata must be at either DATABASE or SCHEMA l
• invalid input for namespace %s, error message: %s

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