apache/iceberg · error · IllegalArgumentException

Invalid option index:

Error message

Invalid option index: 

What it means

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.

Solutions

1. Pass nullIndex of 0 or 1 matching which union branch is null
2. Ensure the Avro schema is a two-branch union with null as exactly one branch
3. Use the standard ValueWriters.option factory instead of custom construction

Example fix

// before
ValueWriters.option(2, writer);
// after
ValueWriters.option(0, writer); // null at branch 0, value at branch 1

if (nullIndex != 0 && nullIndex != 1) throw new IllegalArgumentException("nullIndex must be 0 or 1, got " + nullIndex);

try { ValueWriter<T> w = ValueWriters.option(nullIndex, inner); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Invalid option index")) { /* fix branch order */ } else throw e; }

When it happens

Trigger: 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.

Common situations: Custom Avro unions with more than two branches or reordered branches; incorrect programmatic construction of ValueWriters.option.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• The Avro schema is not a nullable type:
• The Avro schema is not a nullable type
• Avro does not support AAD prefix
• Avro does not support file encryption keys
• Avro does not support LOCAL TIMESTAMP type with precision

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/a050af10d04a6939. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/avro/ValueWriters.java:474

    public void write(Variant variant, Encoder encoder) throws IOException {
      metadataWriter.write(variant.metadata(), encoder);
      valueWriter.write(variant.value(), encoder);
    }
  }

  private static class OptionWriter<T> implements ValueWriter<T> {
    private final int nullIndex;
    private final int valueIndex;
    private final ValueWriter<T> valueWriter;

    private OptionWriter(int nullIndex, ValueWriter<T> valueWriter) {
      this.nullIndex = nullIndex;
      if (nullIndex == 0) {
        this.valueIndex = 1;
      } else if (nullIndex == 1) {
        this.valueIndex = 0;
      } else {
        throw new IllegalArgumentException("Invalid option index: " + nullIndex);
      }
      this.valueWriter = valueWriter;
    }

    @Override
    public void write(T option, Encoder encoder) throws IOException {
      if (option == null) {
        encoder.writeIndex(nullIndex);
      } else {
        encoder.writeIndex(valueIndex);
        valueWriter.write(option, encoder);
      }
    }
  }

  private static class CollectionWriter<T> implements ValueWriter<Collection<T>> {
    private final ValueWriter<T> elementWriter;

View on GitHub (pinned to 86d9c8fc54)