{"record":{"id":"986f6ae2411ae322","repo":"apache/iceberg","slug":"unknown-type-for-binary-field-type-name-986f6a","errorCode":null,"errorMessage":"Unknown type for binary field. Type name: ","messagePattern":"Unknown type for binary field\\. Type name: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/StructInternalRow.java","lineNumber":205,"sourceCode":"    return UTF8String.fromString(seq.toString());\n  }\n\n  @Override\n  public byte[] getBinary(int ordinal) {\n    return isNullAt(ordinal) ? null : getBinaryInternal(ordinal);\n  }\n\n  private byte[] getBinaryInternal(int ordinal) {\n    return toByteArray(struct.get(ordinal, Object.class));\n  }\n\n  private static byte[] toByteArray(Object bytes) {\n    if (bytes instanceof ByteBuffer) {\n      return ByteBuffers.toByteArray((ByteBuffer) bytes);\n    } else if (bytes instanceof byte[]) {\n      return (byte[]) bytes;\n    } else {\n      throw new IllegalStateException(\n          \"Unknown type for binary field. Type name: \" + bytes.getClass().getName());\n    }\n  }\n\n  @Override\n  public BinaryView getBinaryView(int ordinal) {\n    return isNullAt(ordinal)\n        ? null\n        : toBinaryView(type.fields().get(ordinal).type(), getBinaryInternal(ordinal));\n  }\n\n  @Override\n  public CalendarInterval getInterval(int ordinal) {\n    throw new UnsupportedOperationException(\"Unsupported type: interval\");\n  }\n\n  @Override\n  public InternalRow getStruct(int ordinal, int numFields) {","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/StructInternalRow.java#L187-L223","documentation":"toByteArray in StructInternalRow converts a binary field value into a byte[]. If the stored value is neither a ByteBuffer nor a byte[], Iceberg throws IllegalStateException because it cannot interpret the object as binary data. This indicates internal type corruption or misuse of the row accessor rather than an expected user error.","triggerScenarios":"Reading a Spark row via StructInternalRow where getBinaryInternal returns an object that is neither ByteBuffer nor byte[] — e.g. a custom or unexpected value object stored in a binary column, or a version mismatch between the writer that stored the value and the reader.","commonSituations":"Reading tables written by other engines/writers that stored binary values in unexpected Java types; custom catalog or FileIO integrations that bypass standard value conversions; upgrading Iceberg versions where internal representation changed.","solutions":["Check which class name is printed in the message and find where that value type is written; convert it to ByteBuffer/byte[] at write time","Verify writer and reader use compatible Iceberg versions for the table format","Inspect the custom value source (FileIO/catalog plugin) that supplies binary column values","If caused by Iceberg itself, report/upgrade to a fixed version"],"exampleFix":"// before: passing a String-wrapped value into a binary field\nrow.set(ordinal, someString);\n// after\nrow.set(ordinal, ByteBuffer.wrap(someString.getBytes(StandardCharsets.UTF_8)));","handlingStrategy":"type-guard","validationCode":"Object v = row.get(ordinal);\nif (!(v instanceof ByteBuffer) && !(v instanceof byte[])) {\n  throw new IllegalArgumentException(\"Unexpected binary value type: \" + v.getClass());\n}","typeGuard":"static boolean isSupportedBinary(Object v) {\n  return v instanceof ByteBuffer || v instanceof byte[];\n}","tryCatchPattern":"try {\n  byte[] b = row.getBinary(ordinal);\n} catch (IllegalStateException e) {\n  log.error(\"Unsupported binary value in column {}: {}\", ordinal, e.getMessage());\n}","preventionTips":["Only write ByteBuffer or byte[] into binary columns","Keep writer and reader Iceberg versions aligned","Test cross-engine table reads in CI"],"tags":["spark","binary","internal-state"],"backgroundTag":"internal-invariant-violation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}