{"record":{"id":"ba94e016d6275b7e","repo":"apache/iceberg","slug":"tobytebuffer-is-not-supported","errorCode":null,"errorMessage":"toByteBuffer is not supported","messagePattern":"toByteBuffer is not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/expressions/Literal.java","lineNumber":113,"sourceCode":"   * @return A literal of the given type or null if conversion was not valid\n   */\n  <X> Literal<X> to(Type type);\n\n  /**\n   * Return a {@link Comparator} for values.\n   *\n   * @return a comparator for T objects\n   */\n  Comparator<T> comparator();\n\n  /**\n   * Serializes the value wrapped by this literal to binary using the single-value serialization\n   * format described in the Iceberg table specification.\n   *\n   * @return a ByteBuffer that contains the serialized literal value.\n   */\n  default ByteBuffer toByteBuffer() {\n    throw new UnsupportedOperationException(\"toByteBuffer is not supported\");\n  }\n}\n","sourceCodeStart":95,"sourceCodeEnd":116,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/expressions/Literal.java#L95-L116","documentation":"Literal.toByteBuffer() is a default method on the Literal interface that throws UnsupportedOperationException because not every literal can be serialized to Iceberg's single-value binary format. Sentinel literals such as AboveMax, BelowMin, and other special literals have no concrete value to serialize. It is thrown when code asks a non-serializable literal for its binary representation.","triggerScenarios":"Calling literal.toByteBuffer() on a sentinel literal (AboveMax/BelowMin from conversions, count-star-like special literals) or any Literal subclass that intentionally does not implement serialization; e.g. converting an expression's literals to lower/upper bounds or writing them to manifest/parquet statistics.","commonSituations":"Pushing filter literals into file statistics or prefix computations (truncate/prefixAsBytes) when the expression contains aboveMax/belowMin produced by Literal.to(Type) conversions that overflow the target type.","solutions":["Check the literal type before serializing (skip AboveMax/BelowMin and other sentinel literals)","Use Literals.value() only on concrete value literals; treat sentinels specially (e.g. as +/- infinity bounds)","Catch UnsupportedOperationException and handle sentinel literals explicitly in the conversion code"],"exampleFix":"// before\nByteBuffer buf = lit.toByteBuffer(); // throws for AboveMax\n// after\nByteBuffer buf = (lit instanceof Literals.AboveMax || lit instanceof Literals.BelowMin)\n    ? null : lit.toByteBuffer();","handlingStrategy":"type-guard","validationCode":"boolean serializable = !(lit instanceof Literals.AboveMax)\n    && !(lit instanceof Literals.BelowMin);","typeGuard":"static boolean hasByteBuffer(Literal<?> lit) {\n  return !(lit instanceof Literals.AboveMax) && !(lit instanceof Literals.BelowMin);\n}","tryCatchPattern":"ByteBuffer buf;\ntry {\n  buf = lit.toByteBuffer();\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"toByteBuffer is not supported\")) {\n    buf = null; // sentinel literal, skip bound extraction\n  } else {\n    throw e;\n  }\n}","preventionTips":["Skip AboveMax/BelowMin sentinels when collecting literals for statistics or bounds","Check whether toByteBuffer is overridden (it is a default throwing method) before calling it generically","When converting literals with to(Type), expect sentinels on overflow and handle them downstream"],"tags":["java","literals","serialization","sentinel-literal"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}