apache/iceberg · error

Unable to parse table identifier

Error message

Unable to parse table identifier: %s

What it means

`SparkTableUtil.getPartitions(spark, table)` parses the string table identifier with Spark's SQL parser. If the string is not a syntactically valid table identifier (e.g. `db.table` or quoted names), the parser throws a ParseException which is wrapped into this unchecked exception with the offending string interpolated.

Solutions

1. Pass a valid identifier, quoting special parts with backticks: `` `my-db`.`my.table` ``
2. Use the `getPartitions(spark, db, table, ...)` overload that avoids string parsing
3. Validate/split the identifier string before calling
4. Check that no whitespace/URI was accidentally passed

Example fix

// before
SparkTableUtil.getPartitions(spark, "my-db.my.table")
// after
SparkTableUtil.getPartitions(spark, "`my-db`.`my.table`")
// or
SparkTableUtil.getPartitions(spark, "my-db", "my.table", null, Map.empty, partitionFilter)

if (!table.matches("`?[\\w]+`?([.]`?[\\w]+`?)?")) {
  throw new IllegalArgumentException("Expected [db.]table identifier, got: " + table);
}

try { SparkTableUtil.getPartitions(spark, table) } catch { case e: RuntimeException if e.getMessage.startsWith("Unable to parse table identifier") => /* fix identifier or use overload */ }

When it happens

Trigger: Calling `SparkTableUtil.getPartitions(spark, table)` (raised in getPartitions, called by partitions) with a malformed identifier string such as an unquoted name containing special characters, a full URI, or an empty string.

Common situations: Passing a path or file location instead of a table name; special characters (dots, dashes) without backtick quoting; confusing multi-part identifiers with the 3-arg overload that takes db/table separately.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Cannot parse
• Cannot pass path based identifier to
• Cannot pass path based identifier to
• Cannot pass path based identifier to
• No such table

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

Appendix: source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkTableUtil.java:180

    List<SparkPartition> partitions = getPartitionsByFilter(spark, table, expression);
    return spark
        .createDataFrame(partitions, SparkPartition.class)
        .toDF("partition", "uri", "format");
  }

  /**
   * Returns all partitions in the table.
   *
   * @param spark a Spark session
   * @param table a table name and (optional) database
   * @return all table's partitions
   */
  public static List<SparkPartition> getPartitions(SparkSession spark, String table) {
    try {
      TableIdentifier tableIdent = spark.sessionState().sqlParser().parseTableIdentifier(table);
      return getPartitions(spark, tableIdent, null);
    } catch (ParseException e) {
      throw SparkExceptionUtil.toUncheckedException(
          e, "Unable to parse table identifier: %s", table);
    }
  }

  /**
   * Returns all partitions in the table.
   *
   * @param spark a Spark session
   * @param tableIdent a table identifier
   * @param partitionFilter partition filter, or null if no filter
   * @return all table's partitions
   */
  public static List<SparkPartition> getPartitions(
      SparkSession spark, TableIdentifier tableIdent, Map<String, String> partitionFilter) {
    try {
      SessionCatalog catalog = spark.sessionState().catalog();
      CatalogTable catalogTable = catalog.getTableMetadata(tableIdent);

View on GitHub (pinned to 86d9c8fc54)