apache/iceberg · error

Cannot parse type string to primitive: + typeString

Error message

Cannot parse type string to primitive: + typeString

What it means

Thrown by Types.fromTypeName when a type string does not match any known Iceberg type name or pattern (simple types like 'long', parameterized 'decimal(p,s)', 'fixed(n)', 'geometry(crs)', 'geography(crs,alg)'). The string failed the TYPES map lookup and all regex matchers, so it cannot be parsed into a Type.

Source

Thrown at api/src/main/java/org/apache/iceberg/types/Types.java:106

    if (geography.matches()) {
      String crs = geography.group(1);
      String algorithmName = geography.group(2);
      EdgeAlgorithm algorithm =
          algorithmName == null ? null : EdgeAlgorithm.fromName(algorithmName);
      return GeographyType.of(crs, algorithm);
    }

    Matcher fixed = FIXED.matcher(lowerTypeString);
    if (fixed.matches()) {
      return FixedType.ofLength(Integer.parseInt(fixed.group(1)));
    }

    Matcher decimal = DECIMAL.matcher(lowerTypeString);
    if (decimal.matches()) {
      return DecimalType.of(Integer.parseInt(decimal.group(1)), Integer.parseInt(decimal.group(2)));
    }

    throw new IllegalArgumentException("Cannot parse type string to primitive: " + typeString);
  }

  public static PrimitiveType fromPrimitiveString(String typeString) {
    Type type = fromTypeName(typeString);
    if (type.isPrimitiveType()) {
      return type.asPrimitiveType();
    }

    throw new IllegalArgumentException("Cannot parse type string: variant is not a primitive type");
  }

  public static class BooleanType extends PrimitiveType {
    private static final BooleanType INSTANCE = new BooleanType();

    public static BooleanType get() {
      return INSTANCE;
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use exact Iceberg type names: boolean, int, long, float, double, decimal(p,s), date, time, timestamp, timestamptz, string, uuid, fixed(n), binary, geometry, geography, variant
2. For decimals include both precision and scale: decimal(38,10) not decimal(38)
3. Translate engine-specific type names to Iceberg names before calling (e.g. numeric -> decimal)
4. Trim whitespace and verify spelling; the string is matched case-insensitively but must otherwise be exact

Example fix

// before
Type t = Types.fromTypeName("numeric(38,10)");
// after
Type t = Types.fromTypeName("decimal(38,10)");

// check type string against known Iceberg type names before parsing
boolean known = java.util.Set.of("boolean","int","long","float","double","date","time","timestamp","timestamptz","string","uuid","binary","variant").contains(typeString.toLowerCase(Locale.ROOT))
    || typeString.toLowerCase(Locale.ROOT).matches("decimal\\(\\s*\\d+\\s*,\\s*\\d+\\s*\\)")
    || typeString.toLowerCase(Locale.ROOT).matches("fixed\\(\\s*\\d+\\s*\\)");

boolean isParsableIcebergType(String s) {
  try { Types.fromTypeName(s); return true; } catch (IllegalArgumentException e) { return false; }
}

try {
  Type type = Types.fromTypeName(typeString);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Unknown Iceberg type string: " + typeString, e);
}

When it happens

Trigger: Calling Types.fromTypeName (directly or via fromPrimitiveString/type) with a string like 'Decimal(38,10)' without lowercase-normalizable spelling, 'decimal(38)' (missing scale), 'varchar(20)', or any misspelled/unregistered type name.

Common situations: Schema definitions parsed from user config, DDL translation from other systems (e.g. passing Spark's 'string' fine, but 'int64', 'text', or 'numeric' are not Iceberg names), typos in type strings in table properties or SQL catalogs.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Field + name + not found in source schema
• Cannot parse type string: variant is not a primitive type
• Invalid default value for %s: %s (must be null)
• Cannot parse default as a %s value: %s
• Type: %s is not supported

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