apache/beam · error · InvalidPropertyException

Invalid write disposition

Error message

Invalid write disposition '%s'. Supported write dispositions are: %s.

What it means

During BigQueryTable construction, the write_disposition property is uppercased and validated against valid values (e.g. WRITE_APPEND, WRITE_EMPTY, WRITE_TRUNCATE). An unrecognized value throws InvalidPropertyException with the offending value and the list of supported dispositions.

Solutions

1. Use one of the valid dispositions listed in the error (WRITE_APPEND, WRITE_EMPTY, WRITE_TRUNCATE)
2. Correct the property name/value in the CREATE EXTERNAL TABLE WITH options
3. Verify against the BigQueryTable WRITE_DISPOSITION constants for your Beam version

Example fix

// before
WITH write_disposition='OVERWRITE'
// after
WITH write_disposition='WRITE_TRUNCATE'

// before DDL
Set<String> valid = Set.of("WRITE_APPEND", "WRITE_EMPTY", "WRITE_TRUNCATE");
String wd = props.get("write_disposition").asText().toUpperCase();
if (!valid.contains(wd)) throw new IllegalArgumentException("write_disposition must be one of " + valid);

boolean isValidWriteDisposition(String s) {
  try { WriteDisposition.valueOf(s.toUpperCase()); return true; } catch (IllegalArgumentException e) { return false; }
}

try {
  createBigQueryTable(properties);
} catch (InvalidPropertyException e) {
  if (e.getMessage().startsWith("Invalid write disposition")) { /* correct WITH clause */ }
  throw e;
}

When it happens

Trigger: Creating a BigQuery table whose properties contain write_disposition set to an unknown string — typo like 'APPEND' or 'OVERWRITE' instead of the BigQuery API names, or mixed-case values not matching after uppercasing.

Common situations: Mapping habits from other systems (e.g. Spark's 'overwrite') into Beam's BigQuery DDL options; hand-edited pipeline config files; docs drift across Beam versions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid method ' '. Supported methods are: .
• Encountered an unexpected node type
• Only INT64 is supported as the interval value for BigQuery.
• Predicate node ' ' should be a boolean expression, but was
• Unable to unparse with operands.

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

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/bigquery/BigQueryTable.java:118

                + ".");
      }
    } else {
      method = Method.DIRECT_READ;
    }

    LOG.info("BigQuery method is set to: {}", method);

    if (table.getProperties().has(WRITE_DISPOSITION_PROPERTY)) {
      List<String> validWriteDispositions =
          Arrays.stream(WriteDisposition.values()).map(Enum::toString).collect(Collectors.toList());
      // toUpperCase should make it case-insensitive
      String selectedWriteDisposition =
          table.getProperties().get(WRITE_DISPOSITION_PROPERTY).asText().toUpperCase();

      if (validWriteDispositions.contains(selectedWriteDisposition)) {
        writeDisposition = WriteDisposition.valueOf(selectedWriteDisposition);
      } else {
        throw new InvalidPropertyException(
            "Invalid write disposition "
                + "'"
                + selectedWriteDisposition
                + "'. "
                + "Supported write dispositions are: "
                + validWriteDispositions.toString()
                + ".");
      }
    } else {
      writeDisposition = WriteDisposition.WRITE_EMPTY;
    }

    LOG.info("BigQuery writeDisposition is set to: {}", writeDisposition);
  }

  @Override
  public BeamTableStatistics getTableStatistics(PipelineOptions options) {

View on GitHub (pinned to 12126d8942)