{"record":{"id":"c2b240abb8c0cafa","repo":"apache/iceberg","slug":"cannot-pass-path-based-identifier-to-s-method-s","errorCode":null,"errorMessage":"Cannot pass path based identifier to %s method. %s is a path.","messagePattern":"Cannot pass path based identifier to (.+?) method\\. (.+?) is a path\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":885,"sourceCode":"\n    if (!propertyChanges.isEmpty()) {\n      Spark3Util.applyPropertyChanges(transaction.updateProperties(), propertyChanges).commit();\n    }\n\n    if (!schemaChanges.isEmpty()) {\n      Spark3Util.applySchemaChanges(transaction.updateSchema(), schemaChanges).commit();\n    }\n\n    transaction.commitTransaction();\n  }\n\n  private static boolean isPathIdentifier(Identifier ident) {\n    return ident instanceof PathIdentifier;\n  }\n\n  private static void checkNotPathIdentifier(Identifier identifier, String method) {\n    if (identifier instanceof PathIdentifier) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"Cannot pass path based identifier to %s method. %s is a path.\", method, identifier));\n    }\n  }\n\n  private Table load(Identifier ident) {\n    if (isPathIdentifier(ident)) {\n      return loadFromPathIdentifier((PathIdentifier) ident);\n    }\n\n    try {\n      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));\n      return new SparkTable(table, !cacheEnabled);\n\n    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {\n      if (ident.namespace().length == 0) {\n        throw e;\n      }","sourceCodeStart":867,"sourceCodeEnd":903,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L867-L903","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nIdentifier ident = Spark3Util.identifierToPathIdentifier(Spark3Util.makeIdentifier(identString));\ncatalog.createTable(ident, schema, spec, props); // throws\n// after\nIdentifier ident = Spark3Util.makeIdentifier(\"db.tbl\");\ncatalog.createTable(ident, schema, spec, props);","handlingStrategy":"type-guard","validationCode":"if (identifier instanceof PathIdentifier) { throw new IllegalArgumentException(\"use a named identifier, not a path\"); }","typeGuard":"boolean isNamed = !(ident instanceof PathIdentifier);","tryCatchPattern":"try { catalog.stageCreate(ident, schema, spec, props); } catch (IllegalArgumentException e) { /* resolve path to table name and retry */ }","preventionTips":["Never pass file paths to catalog CRUD methods","Parse identifiers with Spark3Util.makeIdentifier","Use spark.read().load(path) for path-based reads"],"tags":["spark","identifier","path","invalid-argument"],"backgroundTag":"invalid-argument-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}