apache/beam · error · IllegalArgumentException

lenientFormat(errorMessageTemplate, errorMessageArgs)

Error message

lenientFormat(errorMessageTemplate, errorMessageArgs)

What it means

The varargs overload of checkArgumentNotNull throws IllegalArgumentException with a formatted message (lenientFormat of template and args) when the reference is null, giving detailed context like Guava's %s-style templates.

Source

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

   * @param errorMessageTemplate a template for the exception message should the check fail. The
   *     message is formed by replacing each {@code %s} placeholder in the template with an
   *     argument. These are matched by position - the first {@code %s} gets {@code
   *     errorMessageArgs[0]}, etc. Unmatched arguments will be appended to the formatted message in
   *     square braces. Unmatched placeholders will be left as-is.
   * @param errorMessageArgs the arguments to be substituted into the message template. Arguments
   *     are converted to strings using {@link String#valueOf(Object)}.
   * @return the non-null reference that was validated
   * @throws IllegalArgumentException if {@code reference} is null
   */
  @CanIgnoreReturnValue
  @EnsuresNonNull("reference")
  @Pure
  public static <T extends @NonNull Object> T checkArgumentNotNull(
      @Nullable T reference,
      @Nullable String errorMessageTemplate,
      @Nullable Object... errorMessageArgs) {
    if (reference == null) {
      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, errorMessageArgs));
    }
    return reference;
  }

  /**
   * 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) {
    if (obj == null) {
      throw new IllegalArgumentException(lenientFormat(errorMessageTemplate, p1));
    }
    return obj;

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the code so the validated value is non-null (initialize, default, or fail earlier).
2. Read the formatted message to identify the offending parameter.
3. Move validation earlier (fail fast at configuration time).

Example fix

// before
Preconditions.checkArgumentNotNull(path, "Path %s not resolved", id);
// after
Preconditions.checkArgumentNotNull(resolve(id), "Path %s not resolved", id);

if (ref == null) throw new IllegalArgumentException(String.format(template, args));

null

try { apiCall(ref); } catch (IllegalArgumentException e) { LOG.error("validation failed: {}", e.getMessage()); }

When it happens

Trigger: Passing null to an API validating with checkArgumentNotNull(ref, template, args...). The template uses %s placeholders; args may be empty.

Common situations: Nullable configuration or computed values (e.g. resolved file paths, credentials) reaching Beam APIs and failing with the formatted message explaining the expectation.

Related errors

• IllegalArgumentException
• String.valueOf(errorMessage)
• lenientFormat(errorMessageTemplate, p1)
• lenientFormat(errorMessageTemplate, p1, p2)
• Secret option string cannot be null

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