apache/iceberg · error

Unable to parse the table identifier: %s

Error message

Unable to parse the table identifier: %s

What it means

Thrown when Spark's SQL parser fails to parse the given string as a table identifier in getPartitionsByFilter(spark, table, predicate). SparkTableUtil wraps the ParseException into an unchecked exception naming the offending input.

Source

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

          e, "Unknown table: %s. Table not found in catalog.", tableIdent);
    }
  }

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

    Expression unresolvedPredicateExpr;
    try {
      unresolvedPredicateExpr = spark.sessionState().sqlParser().parseExpression(predicate);
    } catch (ParseException e) {
      throw SparkExceptionUtil.toUncheckedException(
          e, "Unable to parse the predicate expression: %s", predicate);
    }

    Expression resolvedPredicateExpr = resolveAttrs(spark, table, unresolvedPredicateExpr);
    return getPartitionsByFilter(spark, tableIdent, resolvedPredicateExpr);
  }

  /**
   * Returns partitions that match the specified 'predicate'.
   *

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Quote special characters with backticks: `my-catalog`.`db`.`table-name`.
2. Validate the identifier parses before use: spark.sessionState().sqlParser().parseTableIdentifier(table) in a dry run.
3. Check argument order — the table string must come before the predicate string.
4. Strip whitespace/invalid tokens when the identifier is built dynamically.

Example fix

// before
SparkTableUtil.getPartitionsByFilter(spark, "db.my-table ts > 100", "");
// after
SparkTableUtil.getPartitionsByFilter(spark, "db.`my-table`", "ts > 100");

try {
  spark.sessionState().sqlParser().parseTableIdentifier(table);
} catch (ParseException e) {
  throw new IllegalArgumentException("Invalid table identifier: " + table, e);
}

try {
  SparkTableUtil.getPartitionsByFilter(spark, table, predicate);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unable to parse the table identifier")) {
    throw new IllegalArgumentException("Bad table identifier: " + table, e);
  }
  throw e;
}

When it happens

Trigger: Calling SparkTableUtil.getPartitionsByFilter(spark, table, predicate) where `table` is not a valid identifier — empty string, extra tokens, unquoted special characters (dots, hyphens, spaces), or accidental predicate text pasted into the table argument.

Common situations: Programmatically assembled identifiers containing unescaped dots; forgetting backticks around names with special chars; passing a fully qualified v2 catalog identifier the session parser rejects; swapping the table and predicate arguments by mistake.

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

• Unable to parse sortOrder: %s
• Cannot parse :
• Cannot parse ${description}: ${name}
• Cannot parse <description>: <name>
• e.message (wrapped as IcebergParseException with command con

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