apache/iceberg · error · IllegalArgumentException

Cannot write null to required string column

Error message

Cannot write null to required string column

What it means

The string ValueWriter in ValueWriters writes Utf8 or String values into a required (non-nullable) column; when the value is null, it cannot be encoded, so this IllegalArgumentException is thrown. Nulls require an optional column or a writer that handles nulls.

Source

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

    }
  }

  private static class StringWriter implements ValueWriter<Object> {
    private static final StringWriter INSTANCE = new StringWriter();

    private StringWriter() {}

    @Override
    public void write(Object s, Encoder encoder) throws IOException {
      // use getBytes because it may return the backing byte array if available.
      // otherwise, it copies to a new byte array, which is still cheaper than Avro
      // calling toString, which incurs encoding costs
      if (s instanceof Utf8) {
        encoder.writeString((Utf8) s);
      } else if (s instanceof String) {
        encoder.writeString(new Utf8((String) s));
      } else if (s == null) {
        throw new IllegalArgumentException("Cannot write null to required string column");
      } else {
        throw new IllegalArgumentException(
            "Cannot write unknown string type: " + s.getClass().getName() + ": " + s);
      }
    }
  }

  private static class Utf8Writer implements ValueWriter<Utf8> {
    private static final Utf8Writer INSTANCE = new Utf8Writer();

    private Utf8Writer() {}

    @Override
    public void write(Utf8 s, Encoder encoder) throws IOException {
      encoder.writeString(s);
    }
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Coerce nulls before writing (default value, empty string, or drop the row)
2. Make the column optional in the table schema so null is a valid value
3. Ensure the writer used matches nullability (a nullable writer wraps with option writer)

Example fix

// before
String val = maybeNull();
writer.write(val, encoder);
// after
writer.write(val == null ? "" : val, encoder);

if (value == null && column.isRequired()) throw new IllegalArgumentException("null for required string column: " + column.name());

String requireNonNullString(String s) { return Objects.requireNonNull(s, "required string value is null"); }

try { writer.writeValue(encoder, s); } catch (IllegalArgumentException e) { if (e.getMessage().equals("Cannot write null to required string column")) { /* default value or make column optional */ } else throw e; }

When it happens

Trigger: Writing a record where a String field mapped to a required column carries null; using ValuesWriter with a non-nullable schema but supplying null values.

Common situations: Mismatch between nullable data source and Iceberg required column; missing default/coalesce logic in the ETL before writing.

Related errors

• Cannot write unknown string type:
• Unsupported logical type:
• Unsupported type: ${type}
• Failed to create output stream for location:
• Cannot read manifest list file: %s

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