apache/beam · error · IllegalArgumentException

Could not find a partition term for '{}'.

Error message

Could not find a partition term for '{}'.

What it means

PartitionUtils.toIcebergTerm parses a partition-field expression string into an Iceberg partition term using a list of regex matchers. When no matcher matches the given string, IllegalArgumentException is thrown, meaning the expression syntax is unrecognized.

Source

Thrown at sdks/java/io/iceberg/src/main/java/org/apache/beam/sdk/io/iceberg/PartitionUtils.java:146

                  checkStateNotNull(matcher.group(1)),
                  Integer.parseInt(checkStateNotNull(matcher.group(2)))),
          BUCKET,
          matcher ->
              Expressions.bucket(
                  checkStateNotNull(matcher.group(1)),
                  Integer.parseInt(checkStateNotNull(matcher.group(2)))),
          IDENTITY,
          matcher -> Expressions.ref(checkStateNotNull(matcher.group(1))));

  static Term toIcebergTerm(String field) {
    for (Map.Entry<Pattern, Function<Matcher, Term>> entry : TERMS.entrySet()) {
      Matcher matcher = entry.getKey().matcher(field);
      if (matcher.find()) {
        return entry.getValue().apply(matcher);
      }
    }

    throw new IllegalArgumentException("Could not find a partition term for '" + field + "'.");
  }

  /**
   * Copied over from Apache Iceberg's <a
   * href="https://github.com/apache/iceberg/blob/main/core/src/main/java/org/apache/iceberg/util/PartitionUtil.java">PartitionUtil</a>.
   *
   * <p>Needed to accommodate CDC reads, where scans produce {@link ChangelogScanTask}s instead of
   * {@link ContentScanTask}s.
   */
  public static Map<Integer, ?> constantsMap(
      PartitionSpec spec, ContentFile<?> file, @Nullable Long dataSequenceNumber) {
    Preconditions.checkState(
        spec.specId() == file.specId(),
        "File spec ID (%s) does not match PartitionSpec ID (%s)",
        file.specId(),
        spec.specId());
    StructLike partitionData = file.partition();

View on GitHub (pinned to 12126d8942)

Solutions

1. Match the exact syntax PartitionUtils registers: year/month/day/hour(col), bucket[N](col), truncate[L](col), or bare column name for identity
2. Replace Spark-style names: days->day, hours->hour, years->year before passing
3. Trim whitespace and verify there are no typos in the transform keyword or column name
4. Inspect the term with a quick unit test calling PartitionUtils.toIcebergTerm to confirm it parses before deploying

Example fix

// before
PartitionUtils.toIcebergTerm("days(event_ts)");
// after
PartitionUtils.toIcebergTerm("day(event_ts)");

if (!partitionTerm.matches("(year|month|day|hour)\\(\\w+\\)|(bucket|truncate)\\[\\d+\\]\\(\\w+\\)|^\\w+$")) {
  throw new IllegalArgumentException("Invalid partition term: " + partitionTerm);
}

null

try {
  PartitionSpec.PartitionFieldSpec term = PartitionUtils.toIcebergTerm(field);
} catch (IllegalArgumentException e) {
  LOG.error("Partition term unparsable: {}", e.getMessage());
  // normalize Spark-style names (days->day) and retry
}

When it happens

Trigger: Passing a partition term string to toIcebergTerm (used by dynamic-destination / partition write paths) that no registered regex matches — wrong transform keyword, missing or mispositioned parameters, unsupported syntax such as 'days(ts)' instead of 'day(ts)', or extra whitespace.

Common situations: Translating Iceberg/Spark SQL transform names (days, hours, years, bucket(size)) verbatim into Beam's matcher syntax; typos or case sensitivity issues; writing custom dynamic destination names that embed transform expressions incorrectly.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Could not find a partition transform for '{}'.
• Unknown File Format: {}
• Unrecognized value for stable unique names:
• Secret option string cannot be null
• Secret string must contain a valid type parameter

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