apache/iceberg · error · IllegalArgumentException

Cannot pass path based identifier to %s method. %s is a path

Error message

Cannot pass path based identifier to %s method. %s is a path.

What it means

IllegalArgumentException from checkNotPathIdentifier, thrown by catalog methods (e.g., table/view/namespace operations) that require a named identifier but receive a PathIdentifier (a file path such as 'parquet.`/path/to/data`'). Path-based access is only valid for a subset of methods; passing a path elsewhere is a caller programming error.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:924

    if (!propertyChanges.isEmpty()) {
      Spark3Util.applyPropertyChanges(transaction.updateProperties(), propertyChanges).commit();
    }

    if (!schemaChanges.isEmpty()) {
      Spark3Util.applySchemaChanges(transaction.updateSchema(), schemaChanges).commit();
    }

    transaction.commitTransaction();
  }

  private static boolean isPathIdentifier(Identifier ident) {
    return ident instanceof PathIdentifier;
  }

  private static void checkNotPathIdentifier(Identifier identifier, String method) {
    if (identifier instanceof PathIdentifier) {
      throw new IllegalArgumentException(
          String.format(
              "Cannot pass path based identifier to %s method. %s is a path.", method, identifier));
    }
  }

  private Table load(Identifier ident, TimeTravel timeTravel) throws NoSuchTableException {
    if (isPathIdentifier(ident)) {
      return loadPath((PathIdentifier) ident, timeTravel);
    }

    try {
      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));
      return SparkTable.create(table, timeTravel);

    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {
      if (ident.namespace().length == 0) {
        throw new NoSuchTableException(ident);
      }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use a named identifier (catalog.namespace.table) instead of a file path for this operation
2. Copy/register the path-based data into a named table first (registerTable or CREATE TABLE ... AS SELECT), then perform name-based operations
3. Route path-based reads through spark_catalog instead of the Iceberg catalog

Example fix

// before
catalog.renameTable(sparkPathIdent("/data/t"), namedIdent); // IllegalArgumentException
// after
TableIdentifier ident = TableIdentifier.of(Namespace.of("db"), "t");
catalog.registerTable(namedIdent, "/data/t/metadata/00001-xxx.metadata.json");
catalog.renameTable(ident, newIdent);

if (ident instanceof PathIdentifier) { throw new IllegalArgumentException("Named identifier required for this method"); }

static boolean isNamedIdentifier(Identifier ident) { return !(ident instanceof PathIdentifier); }

try {
  catalog.renameTable(ident, newIdent);
} catch (IllegalArgumentException e) {
  // ident was a path; register the path as a named table first
}

When it happens

Trigger: Calling SparkCatalog methods like createTable, stageReplace, renameTable, registerTable, loadNamespaceMetadata, or view/rename APIs with an Identifier that is a PathIdentifier (SQL statements mixing file paths with operations that require names).

Common situations: Using a file path in RENAME TABLE, namespace DDL, or view statements; SQL frontends generating path identifiers from locations; confusing Spark's path-based tables (spark_catalog with paths) with a named Iceberg catalog.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot pass path based identifier to %s method. %s is a path
• Cannot pass path based identifier to %s method. %s is a path
• Cannot parse %s: %s
• No such table: %s
• Invalid session catalog: sparkSessionCatalog

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