apache/beam · error · IllegalArgumentException

Option is not nullable

Error message

Option %s is not nullable

What it means

Schema.Options.Builder.setOption stores a null option value only when the declared FieldType is nullable. Setting a null value for a non-nullable option type throws IllegalArgumentException 'Option %s is not nullable'.

Solutions

1. Make the option's FieldType nullable: FieldType.of(...).withNullable(true) before passing a null value.
2. Substitute a default non-null value when the option is missing.
3. Skip calling setOption entirely when the value is null instead of storing a null option.

Example fix

// before
builder.setOption("owner", FieldType.STRING, maybeNullOwner);

// after
builder.setOption("owner", FieldType.STRING.withNullable(true), maybeNullOwner);

// Java: guard null option values
if (value == null && !fieldType.getNullable()) {
  value = defaultValue; // or skip setOption
}

When it happens

Trigger: Calling schema.getOptions().setOption(name, FieldType.STRING, null) (or any non-nullable FieldType) with a null value.

Common situations: Propagating optional config into schema options without defaulting; dynamic option construction where the value may be absent.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• No option found with name
• Null field values are not supported
• Arrow schema conversion does not support Beam type
• Cannot call getFromRowFunction when there is no schema
• Cannot call getSchema when there is no schema

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/59d3891120bbe5c2. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/Schema.java:1344

      Builder(Map<String, Option> init) {
        this.options = new HashMap<>(init);
      }

      Builder() {
        this(new HashMap<>());
      }

      public Builder setOption(String optionName, Row value) {
        setOption(optionName, FieldType.row(value.getSchema()), value);
        return this;
      }

      public Builder setOption(String optionName, FieldType fieldType, Object value) {
        if (value == null) {
          if (fieldType.getNullable()) {
            options.put(optionName, new Option(fieldType, null));
          } else {
            throw new IllegalArgumentException(
                String.format("Option %s is not nullable", optionName));
          }
        } else {
          options.put(
              optionName, new Option(fieldType, verifyFieldValue(value, fieldType, optionName)));
        }
        return this;
      }

      public Options build() {
        return new Options(this.options);
      }

      public Builder addOptions(Options options) {
        this.options.putAll(options.options);
        return this;
      }
    }

View on GitHub (pinned to 12126d8942)