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

Thrown by SparkCatalog.checkNotPathIdentifier when an API method that requires a table/view name identifier is given a PathIdentifier (a file path such as '/path/to/table'). Path-based identifiers only support a subset of operations (load, drop, some metadata queries); catalog operations like create, rename, or staged writes require named identifiers.

Source

Thrown at spark/v3.5/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

Use a named table identifier (namespace.table) instead of a file path in the catalog call.
If the goal is to read data from a path, use spark.read.format("iceberg").load(path) instead of the catalog.
Create the table at a named location with the LOCATION clause rather than passing the path as the identifier.
In code, resolve PathIdentifier to a name via Spark3Util before invoking catalog operations.

Example fix

// before
Identifier ident = Spark3Util.identifierToPathIdentifier(Spark3Util.makeIdentifier(identString));
catalog.createTable(ident, schema, spec, props); // throws
// after
Identifier ident = Spark3Util.makeIdentifier("db.tbl");
catalog.createTable(ident, schema, spec, props);

Defensive patterns

Strategy: type-guard

Validate before calling

if (identifier instanceof PathIdentifier) { throw new IllegalArgumentException("use a named identifier, not a path"); }

Type guard

boolean isNamed = !(ident instanceof PathIdentifier);

Try / catch

try { catalog.stageCreate(ident, schema, spec, props); } catch (IllegalArgumentException e) { /* resolve path to table name and retry */ }

Prevention

Never pass file paths to catalog CRUD methods
Parse identifiers with Spark3Util.makeIdentifier
Use spark.read().load(path) for path-based reads

When it happens

Trigger: Passing a path (Identifier of type PathIdentifier, produced by spark.read.load('/path') style table refs) into catalog methods guarded by checkNotPathIdentifier — e.g. createTable, stageCreate, stageReplace, renameTable, purgeTable, createView — via SQL like CREATE TABLE '/tmp/t' ... or catalog API calls with a path.

Common situations: Using CREATE TABLE or REPLACE TABLE with a file location string instead of a table name in Spark SQL; calling catalog.createTable with an Identifier parsed from a path; migrating scripts from Hive (which accepts locations) to Iceberg catalogs.

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/c2b240abb8c0cafa. Report an issue: GitHub.