apache/iceberg · error · IllegalArgumentException

Cannot parse type from json:

Error message

Cannot parse type from json: 

What it means

SchemaParser.typeFromJson(JsonNode) parses a JSON node into an Iceberg Type by matching the 'type' string against known primitive names and complex-type markers (struct/list/map). If the node does not match any known type form, it throws this IllegalArgumentException. It rejects malformed or forward-incompatible type JSON during schema deserialization.

Source

Thrown at core/src/main/java/org/apache/iceberg/SchemaParser.java:195

  private static Type typeFromJson(JsonNode json) {
    if (json.isTextual()) {
      return Types.fromTypeName(json.asText());
    } else if (json.isObject()) {
      JsonNode typeObj = json.get(TYPE);
      if (typeObj != null) {
        String type = typeObj.asText();
        if (STRUCT.equals(type)) {
          return structFromJson(json);
        } else if (LIST.equals(type)) {
          return listFromJson(json);
        } else if (MAP.equals(type)) {
          return mapFromJson(json);
        }
      }
    }

    throw new IllegalArgumentException("Cannot parse type from json: " + json);
  }

  private static Literal<?> defaultFromJson(String defaultField, Type type, JsonNode json) {
    if (json.has(defaultField)) {
      Object value = SingleValueParser.fromJson(type, json.get(defaultField));
      if (type instanceof Types.TimestampNanoType) {
        // Call Expressions.nanos instead of Expressions.lit to prevent overflow
        // https://github.com/apache/iceberg/issues/13160
        return Expressions.nanos((long) value);
      }

      return Expressions.lit(value);
    }

    return null;
  }

  private static Types.NestedField.Builder fieldBuilder(boolean isRequired, String name) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Verify the 'type' value matches an Iceberg type name exactly (boolean, int, long, float, double, decimal(p,s), date, time, timestamp, timestamptz, string, uuid, fixed(n), binary, or object with type: struct/list/map)
2. Upgrade Iceberg on the reading side if the type was written by a newer version
3. Fix typos and remove whitespace; matching is exact, not case-insensitive

Example fix

// before
{"type": "Timestamp"} // wrong casing/format
// after
{"type": "timestamp"} // or "timestamptz" for timestamp with zone

JsonNode typeNode = json.get("type");
Set<String> primitives = Set.of("boolean","int","long","float","double","date","time","timestamp","timestamptz","string","uuid","binary");
boolean ok = typeNode != null && (primitives.contains(typeNode.asText()) || typeNode.asText().startsWith("decimal") || typeNode.asText().startsWith("fixed") || Set.of("struct","list","map").contains(typeNode.asText()));
if (!ok) throw new IllegalArgumentException("Unknown Iceberg type: " + typeNode);

static boolean isKnownTypeJson(JsonNode node) {
  if (node == null || node.get("type") == null) return false;
  String t = node.get("type").asText();
  return t.equals("struct") || t.equals("list") || t.equals("map") || t.matches("(decimal|fixed)\\(.*\\)") || Set.of("boolean","int","long","float","double","date","time","timestamp","timestamptz","string","uuid","binary").contains(t);
}

try {
  return SchemaParser.fromJson(json);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Cannot parse type")) throw new SchemaParseException("Unsupported type in schema JSON: " + e.getMessage(), e);
  throw e;
}

When it happens

Trigger: SchemaParser.fromJson(json) on JSON with an unrecognized 'type' value (typo like 'timestamptz' variants unsupported in that version, 'unknown', empty string), a non-string/non-object type node, or a type name introduced in a newer Iceberg spec version.

Common situations: Schema JSON produced by a newer Iceberg (e.g. unknown/nano types) parsed by an older client; hand-written schema JSON with typos; other frameworks emitting non-Iceberg type descriptors into Iceberg parsers.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unknown task type:
• Cannot write unknown type:
• Cannot parse default as a %s value: %s
• Type: %s is not supported
• Unsupported operation: " + op

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