{"record":{"id":"d8036b6b7a20ecd9","repo":"apache/iceberg","slug":"cannot-pass-path-based-identifier-to-s-method-s-d8036b","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":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":889,"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":871,"sourceCodeEnd":907,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L871-L907","documentation":"SparkCatalog distinguishes table names (namespace-qualified identifiers) from file paths (PathIdentifier, produced when an identifier looks like a location such as '/path/to/table' or 'file:/...'). checkNotPathIdentifier throws this IllegalArgumentException when an API method that only accepts named identifiers is given a path. The message names the offending method and the path that was passed.","triggerScenarios":"Calling SparkCatalog methods like createTable, stageReplace, loadNamespaceMetadata, or other entry points that guard with checkNotPathIdentifier(ident, \"<method>\") while the Identifier is a PathIdentifier — e.g. calling catalog.createTable on a path-style identifier obtained from parsing a location string.","commonSituations":"Programmatic use of the Iceberg Spark catalog extension where an identifier was resolved from a table location; passing a file path where a SQL name is required; a customer-side helper building identifiers from user input that contains '/'.","solutions":["Pass a namespace-qualified Identifier (e.g. Identifier.of(new String[]{\"db\"}, \"table\")) instead of the PathIdentifier.","If you only have a file path, use the path-based API on purpose: loadTable with PathIdentifier is allowed for load, so restrict path usage to load/exists paths, or use HadoopTables directly with the location.","Before calling, check `ident instanceof PathIdentifier` and branch to the correct code path (loadPath semantics) rather than a named-catalog mutation method."],"exampleFix":"// before\ncatalog.createTable(pathIdent, schema, spec); // throws\n\n// after\nif (ident instanceof org.apache.iceberg.spark.PathIdentifier) {\n  throw new IllegalArgumentException(\"Use a named identifier for createTable\");\n}\ncatalog.createTable(Identifier.of(new String[]{\"db\"}, \"table\"), schema, spec);","handlingStrategy":"type-guard","validationCode":"// resolve identifiers from SQL text first, then validate\nif (ident instanceof org.apache.iceberg.spark.PathIdentifier) {\n  throw new IllegalArgumentException(\"Path identifiers are not valid for method \" + methodName);\n}","typeGuard":"boolean isNamedIdentifier(CatalogPlugin.Identifier ident) {\n  return !(ident instanceof org.apache.iceberg.spark.PathIdentifier);\n}","tryCatchPattern":"try {\n  catalog.createTable(ident, schema, spec);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Cannot pass path based identifier\")) {\n    throw new IllegalArgumentException(\"Provide a db.table identifier, not a file path\");\n  }\n  throw e;\n}","preventionTips":["Never construct identifiers from raw user-supplied paths; qualify with catalog/namespace.","Use Spark SQL identifiers (db.table) for mutations; reserve path strings for loadTable on path-qualified reads.","Add an instanceof PathIdentifier check before every catalog extension call."],"tags":["spark","iceberg","illegal-argument","path-identifier","api-misuse"],"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"}