apache/iceberg · error · java.lang.IllegalArgumentException

Cannot parse <description>: <name>

Error message

Cannot parse <description>: <name>

What it means

catalogAndIdentifier parses a table/namespace name string into Spark's Identifier using a SQL parser. If the name is not a valid multipart identifier, the underlying ParseException is rethrown as this IllegalArgumentException, prefixed with the caller-provided description (e.g. 'namespace' or 'table').

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:810

      SparkSession spark, String name, CatalogPlugin defaultCatalog) throws ParseException {
    ParserInterface parser = spark.sessionState().sqlParser();
    Seq<String> multiPartIdentifier = parser.parseMultipartIdentifier(name).toIndexedSeq();
    List<String> javaMultiPartIdentifier = JavaConverters.seqAsJavaList(multiPartIdentifier);
    return catalogAndIdentifier(spark, javaMultiPartIdentifier, defaultCatalog);
  }

  public static CatalogAndIdentifier catalogAndIdentifier(
      String description, SparkSession spark, String name) {
    return catalogAndIdentifier(
        description, spark, name, spark.sessionState().catalogManager().currentCatalog());
  }

  public static CatalogAndIdentifier catalogAndIdentifier(
      String description, SparkSession spark, String name, CatalogPlugin defaultCatalog) {
    try {
      return catalogAndIdentifier(spark, name, defaultCatalog);
    } catch (ParseException e) {
      throw new IllegalArgumentException("Cannot parse " + description + ": " + name, e);
    }
  }

  public static CatalogAndIdentifier catalogAndIdentifier(
      SparkSession spark, List<String> nameParts) {
    return catalogAndIdentifier(
        spark, nameParts, spark.sessionState().catalogManager().currentCatalog());
  }

  /**
   * A modified version of Spark's LookupCatalog.CatalogAndIdentifier.unapply Attempts to find the
   * catalog and identifier a multipart identifier represents
   *
   * @param spark Spark session to use for resolution
   * @param nameParts Multipart identifier representing a table
   * @param defaultCatalog Catalog to use if none is specified
   * @return The CatalogPlugin and Identifier for the table
   */

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Quote problematic identifier parts with backticks: `my.table` instead of my.table.
2. Verify the name has the expected number of parts for catalog.namespace.table resolution.
3. Escape backticks inside identifiers by doubling them (`a``b`).
4. Catch IllegalArgumentException from catalogAndIdentifier and show the user a clearer naming-convention message.

Example fix

// before
String name = "catalog:my.table";
catalogAndIdentifier("table", spark, name, defaultCatalog); // ParseException
// after
String name = "catalog.`my.table`";
catalogAndIdentifier("table", spark, name, defaultCatalog); // ok

// Scala/Java pseudo-check before calling
boolean looksParseable = name != null && !name.trim().isEmpty() &&
    Arrays.stream(name.split("\\."))
          .allMatch(p -> p.isEmpty() || (p.startsWith("`") == p.endsWith("`")));

try {
  CatalogAndIdentifier id = Spark3Util.catalogAndIdentifier("table", spark, name, defaultCatalog);
} catch (IllegalArgumentException e) {
  throw new UserFacingError("Invalid table name '" + name + "'. Quote special parts with backticks.", e);
}

When it happens

Trigger: Calling Spark3Util.catalogAndIdentifier(description, spark, name, defaultCatalog) with a name that fails Spark's parser, e.g. unescaped special characters like my.table, backticks in odd places, or empty parts.

Common situations: Users passing fully-qualified names with unescaped dots or backticks in SQL commands like ALTER TABLE or CREATE TABLE routed through custom catalogs; confusion between catalog.table vs table naming conventions.

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.

Related errors

• Cannot parse :
• Cannot parse ${description}: ${name}
• Unable to parse the table identifier: %s
• Procedure ${ident} not found
• Unable to parse sortOrder: %s

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