{"record":{"id":"706e20e64bb2efde","repo":"apache/beam","slug":"metadata-value-type-must-be-one-of-string-long-or-byte-found","errorCode":null,"errorMessage":"Metadata value type must be one of String, Long, or byte[]. Found ${v.getClass().getSimpleName()}","messagePattern":"Metadata value type must be one of String, Long, or byte\\[\\]\\. Found (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/avro/src/main/java/org/apache/beam/sdk/extensions/avro/io/AvroIO.java","lineNumber":2179,"sourceCode":"      if (getRecordFormatter() != null) {\n        datumWriter = new FormattedDatumWriter<>(schema, getRecordFormatter());\n      } else if (getDatumWriterFactory() != null) {\n        datumWriter = getDatumWriterFactory().apply(schema);\n      } else {\n        datumWriter = new ReflectDatumWriter<>(schema);\n      }\n      writer = new DataFileWriter<>(datumWriter);\n      writer.setCodec(getCodec().getCodec());\n      for (Map.Entry<String, Object> entry : getMetadata().entrySet()) {\n        Object v = entry.getValue();\n        if (v instanceof String) {\n          writer.setMeta(entry.getKey(), (String) v);\n        } else if (v instanceof Long) {\n          writer.setMeta(entry.getKey(), (Long) v);\n        } else if (v instanceof byte[]) {\n          writer.setMeta(entry.getKey(), (byte[]) v);\n        } else {\n          throw new IllegalStateException(\n              \"Metadata value type must be one of String, Long, or byte[]. Found \"\n                  + v.getClass().getSimpleName());\n        }\n      }\n      writer.create(schema, Channels.newOutputStream(channel));\n    }\n\n    @Override\n    public void write(ElementT element) throws IOException {\n      writer.append(element);\n    }\n\n    @Override\n    public void flush() throws IOException {\n      writer.flush();\n    }\n  }\n","sourceCodeStart":2161,"sourceCodeEnd":2197,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/avro/src/main/java/org/apache/beam/sdk/extensions/avro/io/AvroIO.java#L2161-L2197","documentation":"When writing Avro container files through AvroIO.Write, user metadata values may only be String, Long, or byte[] — the types Avro's DataFileWriter.setMeta supports. Any other value type throws IllegalStateException at write setup time.","triggerScenarios":"Passing a Map<String, Object> with metadata (withMetadata) whose values are e.g. Integer, Double, Boolean, or Float to AvroIO.Write.","commonSituations":"Auto-boxed ints from Java literals (Integer instead of Long), JSON-parsed metadata with mixed types, or configuration maps built generically without normalizing types.","solutions":["Convert numeric metadata values to Long explicitly ((long) intValue)","Convert boolean/double values to String or byte[] before passing","Whitelist/transform the metadata map at pipeline construction to the three supported types"],"exampleFix":"// before\nmetadata.put(\"count\", 42);            // Integer\n// after\nmetadata.put(\"count\", 42L);           // Long","handlingStrategy":"type-guard","validationCode":"metadata.values().forEach(v -> {\n  if (!(v instanceof String || v instanceof Long || v instanceof byte[]))\n    throw new IllegalArgumentException(\"Bad metadata type: \" + v.getClass());\n});","typeGuard":"static boolean isAvroMetaType(Object v) {\n  return v instanceof String || v instanceof Long || v instanceof byte[];\n}","tryCatchPattern":"try { writer.create(schema, out); } catch (IllegalStateException e) { /* normalize metadata and retry */ }","preventionTips":["Declare metadata maps as Map<String, Object> only after normalizing types","Use explicit L suffix for numeric metadata","Centralize metadata construction in one typed builder"],"tags":["avro","metadata","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}