{"record":{"id":"a050af10d04a6939","repo":"apache/iceberg","slug":"invalid-option-index","errorCode":null,"errorMessage":"Invalid option index: ","messagePattern":"Invalid option index: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/avro/ValueWriters.java","lineNumber":474,"sourceCode":"    public void write(Variant variant, Encoder encoder) throws IOException {\n      metadataWriter.write(variant.metadata(), encoder);\n      valueWriter.write(variant.value(), encoder);\n    }\n  }\n\n  private static class OptionWriter<T> implements ValueWriter<T> {\n    private final int nullIndex;\n    private final int valueIndex;\n    private final ValueWriter<T> valueWriter;\n\n    private OptionWriter(int nullIndex, ValueWriter<T> valueWriter) {\n      this.nullIndex = nullIndex;\n      if (nullIndex == 0) {\n        this.valueIndex = 1;\n      } else if (nullIndex == 1) {\n        this.valueIndex = 0;\n      } else {\n        throw new IllegalArgumentException(\"Invalid option index: \" + nullIndex);\n      }\n      this.valueWriter = valueWriter;\n    }\n\n    @Override\n    public void write(T option, Encoder encoder) throws IOException {\n      if (option == null) {\n        encoder.writeIndex(nullIndex);\n      } else {\n        encoder.writeIndex(valueIndex);\n        valueWriter.write(option, encoder);\n      }\n    }\n  }\n\n  private static class CollectionWriter<T> implements ValueWriter<Collection<T>> {\n    private final ValueWriter<T> elementWriter;\n","sourceCodeStart":456,"sourceCodeEnd":492,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/avro/ValueWriters.java#L456-L492","documentation":"ValueWriters.optionWriter encodes an optional value as a union of [null, value]; the null branch position must be 0 or 1. Any other nullIndex is invalid and throws this IllegalArgumentException in the constructor.","triggerScenarios":"Constructing an option writer with a nullIndex outside {0,1}; usually only from custom code or a schema whose union branch ordering is not a two-branch [null, T] union.","commonSituations":"Custom Avro unions with more than two branches or reordered branches; incorrect programmatic construction of ValueWriters.option.","solutions":["Pass nullIndex of 0 or 1 matching which union branch is null","Ensure the Avro schema is a two-branch union with null as exactly one branch","Use the standard ValueWriters.option factory instead of custom construction"],"exampleFix":"// before\nValueWriters.option(2, writer);\n// after\nValueWriters.option(0, writer); // null at branch 0, value at branch 1","handlingStrategy":"validation","validationCode":"if (nullIndex != 0 && nullIndex != 1) throw new IllegalArgumentException(\"nullIndex must be 0 or 1, got \" + nullIndex);","typeGuard":null,"tryCatchPattern":"try { ValueWriter<T> w = ValueWriters.option(nullIndex, inner); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Invalid option index\")) { /* fix branch order */ } else throw e; }","preventionTips":["Use the standard option() factory instead of manual construction","Confirm the Avro union is exactly [null, T] or [T, null]","Derive nullIndex from the schema's union branch inspection"],"tags":["avro","union","invalid-index"],"backgroundTag":"value-out-of-range","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"}