What causes "Cannot parse ${description}: ${name}" in apache/iceberg?

Fix the identifier string: valid form is catalog.namespace.table with properly balanced backticks only around parts needing escaping

apache/iceberg · error · IllegalArgumentException

Cannot parse ${description}: ${name}

Error message

Cannot parse ${description}: ${name}

What it means

Spark3Util.catalogAndIdentifier(description, spark, name, defaultCatalog) parses a table/namespace name string using Spark's parser. If the string is not a valid multipart identifier, the underlying ParseException is rethrown as IllegalArgumentException with the supplied description and the offending name.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:827

      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

Fix the identifier string: valid form is catalog.namespace.table with properly balanced backticks only around parts needing escaping
Escape backticks inside identifiers by doubling them (``)
If the name comes from user input, validate/normalize it before calling catalogAndIdentifier

Example fix

// before
Spark3Util.catalogAndIdentifier("table identifier", spark, "my`catalog.tbl", defaultCatalog); // bad backtick placement
// after
Spark3Util.catalogAndIdentifier("table identifier", spark, "my_catalog.default.tbl", defaultCatalog);

Defensive patterns

Strategy: validation

Validate before calling

if (name == null || name.trim().isEmpty() || name.contains("..") || countUnbalanced(name, '`') != 0) { throw new IllegalArgumentException("Malformed identifier: " + name); }

Type guard

boolean looksLikeMultipartIdentifier(String s) { return s != null && !s.startsWith(".") && !s.endsWith(".") && !s.contains(".."); }

Try / catch

try { return Spark3Util.catalogAndIdentifier("table identifier", spark, name, defaultCatalog); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Fix the table name, expected [catalog.][namespace.]table: " + name, e); }

Prevention

Validate identifier strings from user input/CLI before parsing
Remember to double backticks to escape them inside identifiers
Prefer building identifiers from List<String> nameParts via catalogAndIdentifier(spark, nameParts) instead of parsing strings

When it happens

Trigger: Calling Spark3Util.catalogAndIdentifier(description, spark, name, defaultCatalog) (or catalog-based callers like SparkSessionCatalog.loadTable) with a name string Spark's parser cannot parse, e.g. containing stray backticks, unbalanced quotes, or '.' placement like '`db`.`tbl' with a dangling backtick.

Common situations: Typo in CLI/SQL catalog names (extra dot like 'catalog..table'); shell quoting stripping backticks; users passing fully-qualified URIs or SQL fragments as table names; session catalog delegation with malformed identifiers.

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

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