apache/iceberg · error · IllegalArgumentException

Cannot convert identifier

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.

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
• Invalid identifier
• Invalid table identifier
• Invalid view identifier
• 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.

Appendix: 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)