apache/iceberg · error · IllegalArgumentException

Cannot parse :

Error message

Cannot parse : 

What it means

Spark3Util.catalogAndIdentifier(description, spark, name, defaultCatalog) parses an identifier string into a (catalog, namespace, table) triple using Spark's parser. If the name cannot be parsed as a valid multi-part identifier it throws IllegalArgumentException 'Cannot parse <description>: <name>', wrapping the original ParseException.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:780

      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. Fix the identifier string: backtick-quote each part, e.g. `cat`.`ns`.`tbl`, and remove stray whitespace/quotes
2. Pass nameParts as a List<String> via catalogAndIdentifier(spark, List<String>) instead of a raw string to skip parsing
3. Validate the name with a quick parse or regex before calling
4. Catch IllegalArgumentException and surface a clearer message describing expected format

Example fix

// before
catalogAndIdentifier(spark, "my-catalog:db.table") // colon not parseable
// after
catalogAndIdentifier(spark, ImmutableList.of("my-catalog", "db", "table"))

// Quick pre-check: identifier must be non-empty and parse into dot-separated parts
if (name == null || name.isBlank()) {
  throw new IllegalArgumentException("Identifier must be non-empty");
}

boolean isParsableIdentifier(String name) {
  return name != null && !name.isBlank() && !name.startsWith("`") && name.chars().noneMatch(c -> c == ';');
}

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

When it happens

Trigger: Passing a malformed table/identifier string — unbalanced quotes/backticks, empty name, illegal characters — to catalogAndIdentifier or APIs that use it (e.g. loadTable helpers, ALTER/DESCRIBE resolution).

Common situations: Identifiers built by string concatenation with missing backticks around special characters; whitespace or newline typos; programmatic names containing dots not escaped.

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 ${description}: ${name}
• Cannot parse <description>: <name>
• Invalid transform argument
• Unable to parse the table identifier: %s
• Cannot set value

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