apache/iceberg · error · IllegalArgumentException

Cannot convert identifier '%s' to Namespace

Error message

Cannot convert identifier '%s' to Namespace

What it means

NamespaceHelpers.toIcebergNamespace converts a SnowflakeIdentifier into an Iceberg Namespace. Only ROOT, DATABASE, and SCHEMA identifier types have namespace equivalents; a TABLE (or any other) identifier type reaches the default branch and throws IllegalArgumentException. The caller passed the wrong kind of SnowflakeIdentifier.

Source

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

        namespaceScope);
    return SnowflakeIdentifier.ofTable(
        namespaceScope.databaseName(), namespaceScope.schemaName(), identifier.name());
  }

  /**
   * Converts a SnowflakeIdentifier of type ROOT, DATABASE, or SCHEMA into an equivalent Iceberg
   * Namespace; throws IllegalArgumentException if not an appropriate type.
   */
  public static Namespace toIcebergNamespace(SnowflakeIdentifier identifier) {
    switch (identifier.type()) {
      case ROOT:
        return Namespace.empty();
      case DATABASE:
        return Namespace.of(identifier.databaseName());
      case SCHEMA:
        return Namespace.of(identifier.databaseName(), identifier.schemaName());
      default:
        throw new IllegalArgumentException(
            String.format("Cannot convert identifier '%s' to Namespace", identifier));
    }
  }

  /**
   * Converts a SnowflakeIdentifier to an equivalent Iceberg TableIdentifier; the identifier must be
   * of type TABLE.
   */
  public static TableIdentifier toIcebergTableIdentifier(SnowflakeIdentifier identifier) {
    Preconditions.checkArgument(
        identifier.type() == SnowflakeIdentifier.Type.TABLE,
        "SnowflakeIdentifier must be type TABLE, got '%s'",
        identifier);
    return TableIdentifier.of(
        identifier.databaseName(), identifier.schemaName(), identifier.tableName());
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Only pass DATABASE or SCHEMA type SnowflakeIdentifiers to toIcebergNamespace
2. Use NamespaceHelpers.toIcebergTableIdentifier for TABLE-typed identifiers
3. Check identifier.type() and branch to the appropriate conversion helper before converting

Example fix

// before
Namespace ns = NamespaceHelpers.toIcebergNamespace(tableId);
// after
Namespace ns = tableId.isTable()
    ? null
    : NamespaceHelpers.toIcebergNamespace(tableId);
TableIdentifier tbl = NamespaceHelpers.toIcebergTableIdentifier(tableId);

if (id.type() != SnowflakeIdentifierType.DATABASE
    && id.type() != SnowflakeIdentifierType.SCHEMA) {
  throw new IllegalArgumentException("Not a namespace identifier: " + id);
}

boolean isNamespaceIdentifier(SnowflakeIdentifier id) {
  return id.type() == SnowflakeIdentifierType.DATABASE
      || id.type() == SnowflakeIdentifierType.SCHEMA;
}

try {
  Namespace ns = NamespaceHelpers.toIcebergNamespace(id);
} catch (IllegalArgumentException e) {
  // use toIcebergTableIdentifier for TABLE identifiers instead
}

When it happens

Trigger: Passing a SnowflakeIdentifier.ofTable(...) (or another non-namespace type) to code that converts identifiers to namespaces, e.g. when mapping listNamespaces results from custom SnowflakeClient implementations.

Common situations: Custom SnowflakeClient implementations returning TABLE-typed identifiers where DATABASE/SCHEMA results are expected; refactored code mixing toIcebergNamespace with toIcebergTableIdentifier; glue code converting identifiers of the wrong type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Snowflake max namespace level is %d, got namespace '%s'
• Invalid identifier: %s
• Invalid table identifier: %s
• Invalid view identifier: %s
• listNamespaces must be at either ROOT or DATABASE level; got

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