{"record":{"id":"e34702876d270865","repo":"apache/iceberg","slug":"cannot-pass-path-based-identifier-to-s-method-s-e34702","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/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":924,"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, TimeTravel timeTravel) throws NoSuchTableException {\n    if (isPathIdentifier(ident)) {\n      return loadPath((PathIdentifier) ident, timeTravel);\n    }\n\n    try {\n      org.apache.iceberg.Table table = icebergCatalog.loadTable(buildIdentifier(ident));\n      return SparkTable.create(table, timeTravel);\n\n    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {\n      if (ident.namespace().length == 0) {\n        throw new NoSuchTableException(ident);\n      }","sourceCodeStart":906,"sourceCodeEnd":942,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L906-L942","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Use a named identifier (catalog.namespace.table) instead of a file path for this operation","Copy/register the path-based data into a named table first (registerTable or CREATE TABLE ... AS SELECT), then perform name-based operations","Route path-based reads through spark_catalog instead of the Iceberg catalog"],"exampleFix":"// before\ncatalog.renameTable(sparkPathIdent(\"/data/t\"), namedIdent); // IllegalArgumentException\n// after\nTableIdentifier ident = TableIdentifier.of(Namespace.of(\"db\"), \"t\");\ncatalog.registerTable(namedIdent, \"/data/t/metadata/00001-xxx.metadata.json\");\ncatalog.renameTable(ident, newIdent);","handlingStrategy":"type-guard","validationCode":"if (ident instanceof PathIdentifier) { throw new IllegalArgumentException(\"Named identifier required for this method\"); }","typeGuard":"static boolean isNamedIdentifier(Identifier ident) { return !(ident instanceof PathIdentifier); }","tryCatchPattern":"try {\n  catalog.renameTable(ident, newIdent);\n} catch (IllegalArgumentException e) {\n  // ident was a path; register the path as a named table first\n}","preventionTips":["Never mix file-path identifiers with catalog name-based operations","Register path-based metadata as a named table before renaming","Validate identifier type in wrapper helpers before dispatching"],"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"}