apache/beam · error · IllegalArgumentException

lenientFormat(errorMessageTemplate, p1, p2)

Error message

lenientFormat(errorMessageTemplate, p1, p2)

What it means

Apache Beam's Preconditions.checkArgumentNotNull(T, String, char, char) throws IllegalArgumentException when the checked reference is null, formatting the message template with two char substitutions via lenientFormat (Preconditions.java:178). It exists to fail fast on violated non-null contracts with descriptive messages.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/Preconditions.java:178

      @Nullable T obj, @Nullable String errorMessageTemplate, @Nullable Object p1) {
    if (obj == null) {
      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1));
    }
    return obj;
  }

  /**
   * Ensures that an object reference passed as a parameter to the calling method is not null.
   *
   * <p>See {@link #checkArgumentNotNull(Object, String, Object...)} for details.
   */
  @CanIgnoreReturnValue
  @EnsuresNonNull("#1")
  @Pure
  public static <T extends @NonNull Object> T checkArgumentNotNull(
      @Nullable T obj, @Nullable String errorMessageTemplate, char p1, char p2) {
    if (obj == null) {
      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
    }
    return obj;
  }

  /**
   * Ensures that an object reference passed as a parameter to the calling method is not null.
   *
   * <p>See {@link #checkArgumentNotNull(Object, String, Object...)} for details.
   */
  @CanIgnoreReturnValue
  @EnsuresNonNull("#1")
  @Pure
  public static <T extends @NonNull Object> T checkArgumentNotNull(
      @Nullable T obj, @Nullable String errorMessageTemplate, char p1, int p2) {
    if (obj == null) {
      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1, p2));
    }
    return obj;

View on GitHub (pinned to 12126d8942)

Solutions

1. Initialize the flagged reference before the call.
2. Add an explicit null check with a descriptive message at the call site.
3. Use the formatted message (contains the two char substitutions) to locate the failing value.
4. Rework the caller to tolerate null if that is a valid state.

Example fix

// before
String sep = Preconditions.checkArgumentNotNull(cfg.getSeparator(), "bad seps %c%c", a, b);
// after
checkState(cfg.getSeparator() != null, "separator missing (tried %c and %c)", a, b);
String sep = cfg.getSeparator();

if (cfg.getSeparator() == null) {
  throw new IllegalArgumentException("separator must be configured");
}

static <T> boolean nonNull(T v) { return v != null; }

try {
  return Preconditions.checkArgumentNotNull(v, "msg %c%c", a, b);
} catch (IllegalArgumentException e) {
  log.error("null argument: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: Calling checkArgumentNotNull(obj, template, c1, c2) where obj is null.

Common situations: Passing an unset reference into a Beam API that validates non-nullity while supplying two chars (e.g. delimiters, column names) in the error template.

Related errors

• ApproximateUnique.PerKey needs an estimation error between 1
• timerFrequency must be greater than zero
• label + ": " + String.format(message, args)
• must either have a non-empty list of PCollections, or must f
• PCollections come from different Pipelines

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