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

checkNotPathIdentifier throws IllegalArgumentException when a PathIdentifier (an identifier parsed from a file/table path, e.g. 'parquet./path/to/data') is passed to an identifier-only catalog method such as createTable, dropTable, renameTable, or view operations. Path-based identifiers are only valid for load-style operations; mutation/DDL methods require namespace-based identifiers.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:885

    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) {
    if (isPathIdentifier(ident)) {
      return loadFromPathIdentifier((PathIdentifier) ident);
    }

    try {
      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));
      return new SparkTable(table, !cacheEnabled);

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

View on GitHub (pinned to 86d9c8fc54)

Solutions

Register the data as a named table in the catalog and use its namespace.name identifier for DDL.
Use the path-qualified syntax only for read operations (SELECT ... FROM parquet.`/path`).
For tables created from paths, ensure CREATE TABLE ... USING iceberg LOCATION is done through the catalog so an identifier exists.

Example fix

// before
spark.catalog.dropTable("parquet.`/tmp/data/t`") // path identifier: throws
// after
spark.sql("DROP TABLE my_catalog.db.t") // named catalog table

Defensive patterns

Strategy: type-guard

Type guard

boolean isPathIdentifier(org.apache.spark.sql.connector.catalog.Identifier ident) {
  return ident instanceof org.apache.iceberg.spark.PathIdentifier;
}
// guard: if (isPathIdentifier(ident)) resolve a catalog (namespace, name) identifier first

Try / catch

try {
  sparkCatalog.dropTable(ident);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("path based identifier")) { /* convert path table to named table first */ }
  throw e;
}

Prevention

Never pass 'parquet./path' style identifiers to DDL methods.
Register path data as catalog tables before mutating them.
Route path-based reads through SELECT and catalog writes through named tables.

When it happens

Trigger: Calling SparkCatalog.createTable/dropTable/renameTable/alterTable (or view DDL) with an Identifier built from a path string instead of a (namespace, name) pair; passing 'file:///tmp/t' where a table name is expected.

Common situations: Users treating a loaded path-table like a catalog table and then trying DDL on it; Spark SQL statements that resolve to path identifiers via 'parquet.`/path`' syntax; scripts mixing path loads with catalog operations.

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

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