apache/beam · error · RuntimeException

Does not support converting avro format: " +…

Error message

Does not support converting avro format: " + value.getClass().getName()

What it means

Thrown by convertAvroString when the Avro value for a Beam STRING field is neither null, Avro Utf8, nor java.lang.String. The BigQuery Avro path expects string-typed columns decoded to Utf8/String; any other runtime type (e.g. Integer, ByteBuffer, Map from a mis-decoded record) is rejected. Usually indicates a mismatch between the declared Avro schema and the actual decoded values.

Solutions

  1. Configure the Avro decoder with string conversion: new GenericDatumReader<GenericRecord>(schema, schema, new GenericData().addStringConversion(...)) or configure GenericData.StringType.String so values decode as Utf8.
  2. Verify the Avro schema field for the STRING column is actually of type string, not bytes/int.
  3. Check for reader/writer schema mismatch when decoding the GenericRecord.
  4. As a fallback, extend/fork convertAvroString to coerce Number/ByteBuffer values via String.valueOf.

Example fix

// before
GenericDatumReader<GenericRecord> r = new GenericDatumReader<>(schema);
// after
GenericData gd = new GenericData();
gd.setStringType(GenericData.StringType.String);
GenericDatumReader<GenericRecord> r = new GenericDatumReader<>(schema, schema, gd);
Defensive patterns

Strategy: type-guard

Validate before calling

// Java: normalize string values before conversion
Object normalizeString(Object v) {
  if (v instanceof Utf8) return v.toString();
  if (v instanceof String || v == null) return v;
  if (v instanceof Number) return v.toString();
  throw new IllegalArgumentException("Expected avro string, got " + v.getClass());
}

Type guard

// Java
static boolean isAvroString(Object v) {
  return v == null || v instanceof Utf8 || v instanceof String;
}

Try / catch

try { s = convertAvroFormat(stringField, v, opts); } catch (RuntimeException e) { if (e.getMessage().startsWith("Does not support converting avro format")) { s = String.valueOf(v); } else throw e; }

Prevention

When it happens

Trigger: Avro GenericData.Record decoded with a GenericDatumReader without string conversion where values arrive as unexpected types, or BigQuery export/avro schema mismatch where a non-string Avro value feeds a STRING Beam field — e.g. value is Integer/Long/ByteBuffer.

Common situations: Custom avro decoding pipelines feeding records into BigQueryIO conversion; Avro reader/writer schema mismatch; data loaded into BigQuery with wrong types then exported as Avro.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/29a254b7cdbf0eb8. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryUtils.java:1173

        throw new RuntimeException("Does not support converting DECIMAL type value");
      case STRING:
        return convertAvroString(value);
      case BYTES:
        return convertAvroBytes(value);
      default:
        throw new RuntimeException(beamType + " is not primitive type.");
    }
  }

  private static @Nullable Object convertAvroString(@Nullable Object value) {
    if (value == null) {
      return null;
    } else if (value instanceof Utf8) {
      return ((Utf8) value).toString();
    } else if (value instanceof String) {
      return value;
    } else {
      throw new RuntimeException(
          "Does not support converting avro format: " + value.getClass().getName());
    }
  }

  private static @Nullable Object convertAvroBytes(@Nullable Object value) {
    if (value == null) {
      return null;
    } else if (value instanceof ByteBuffer) {
      ByteBuffer bf = (ByteBuffer) value;
      byte[] result = new byte[bf.limit()];
      bf.get(result);
      return result;
    } else {
      throw new RuntimeException(
          "Does not support converting avro format: " + value.getClass().getName());
    }
  }

View on GitHub (pinned to 12126d8942)