What causes "Could not parse Avro schema string." in apache/iceberg?

Validate the schema string with a standalone Avro parser (new Schema.Parser().parse(s)) to see the detailed error

apache/iceberg · error · java.lang.IllegalArgumentException

Could not parse Avro schema string.

Error message

Could not parse Avro schema string.

What it means

AvroSchemaConverter.convertToTypeInfo wraps Avro SchemaParseException in an IllegalArgumentException when the supplied Avro schema string cannot be parsed. The original parse error is preserved as the cause.

Source

Thrown at flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/formats/avro/typeutils/AvroSchemaConverter.java:127

  }

  /**
   * Converts an Avro schema string into a nested row structure with deterministic field order and
   * data types that are compatible with Flink's Table &amp; SQL API.
   *
   * @param avroSchemaString Avro schema definition string
   * @param legacyTimestampMapping legacy mapping of timestamp types
   * @return type information matching the schema
   */
  @SuppressWarnings("unchecked")
  public static <T> TypeInformation<T> convertToTypeInfo(
      String avroSchemaString, boolean legacyTimestampMapping) {
    Preconditions.checkNotNull(avroSchemaString, "Avro schema must not be null.");
    final Schema schema;
    try {
      schema = new Schema.Parser().parse(avroSchemaString);
    } catch (SchemaParseException e) {
      throw new IllegalArgumentException("Could not parse Avro schema string.", e);
    }
    return (TypeInformation<T>) convertToTypeInfo(schema, legacyTimestampMapping);
  }

  private static TypeInformation<?> convertToTypeInfo(
      Schema schema, boolean legacyTimestampMapping) {
    switch (schema.getType()) {
      case RECORD:
        final List<Schema.Field> fields = schema.getFields();

        final TypeInformation<?>[] types = new TypeInformation<?>[fields.size()];
        final String[] names = new String[fields.size()];
        for (int i = 0; i < fields.size(); i++) {
          final Schema.Field field = fields.get(i);
          types[i] = convertToTypeInfo(field.schema(), legacyTimestampMapping);
          names[i] = field.name();
        }
        return Types.ROW_NAMED(names, types);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Validate the schema string with a standalone Avro parser (new Schema.Parser().parse(s)) to see the detailed error
Fix JSON syntax/typos in the schema string; ensure it is the schema, not the container file
Load the schema from a reliable source (file/classpath resource) rather than copy-paste
Check unresolved type references and namespaces in the schema

Example fix

// before: missing closing brace
String s = "{\"type\":\"record\",\"name\":\"R\",\"fields\":[{\"name\":\"a\",\"type\":\"int\"}";
// after
String s = "{\"type\":\"record\",\"name\":\"R\",\"fields\":[{\"name\":\"a\",\"type\":\"int\"}]}";

Defensive patterns

Strategy: validation

Validate before calling

try {
  new Schema.Parser().parse(avroSchemaString);
} catch (SchemaParseException e) {
  throw new IllegalStateException("Invalid Avro schema string: " + e.getMessage(), e);
}

Try / catch

try {
  TypeInformation<?> ti = AvroSchemaConverter.convertToTypeInfo(schemaString, false);
} catch (IllegalArgumentException e) {
  if (e.getMessage().equals("Could not parse Avro schema string.")) {
    // log e.getCause() for the exact parse error and fix the schema
  } else { throw e; }
}

Prevention

Pre-validate schema strings with Schema.Parser before passing them in
Store schemas as classpath/file resources, not inline config strings
Check for truncation when schemas travel through env vars or UI inputs
Keep schemas under version control

When it happens

Trigger: Calling AvroSchemaConverter.convertToTypeInfo(schemaString, ...) with malformed JSON, invalid Avro grammar, unknown type names, or unresolvable references in the schema string.

Common situations: Hand-edited schema strings with typos; schema loaded from a truncated file or environment variable; embedded quotes/newlines mangled when passing schemas through config.

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

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