apache/beam · error · IllegalArgumentException

String.valueOf(errorMessage)

Error message

String.valueOf(errorMessage)

What it means

The two-argument overload of checkArgumentNotNull throws IllegalArgumentException with a caller-supplied message (String.valueOf(errorMessage)) when the reference is null. It exists so failures carry context about which value was unexpectedly null.

Source

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

    return reference;
  }

  /**
   * Ensures that an object reference passed as a parameter to the calling method is not null.
   *
   * @param reference an object reference
   * @param errorMessage the exception message to use if the check fails; will be converted to a
   *     string using {@link String#valueOf(Object)}
   * @return the non-null reference that was validated
   * @throws IllegalArgumentException if {@code reference} is null
   */
  @CanIgnoreReturnValue
  @EnsuresNonNull("#1")
  @Pure
  public static <T extends @NonNull Object> T checkArgumentNotNull(
      @Nullable T reference, @Nullable Object errorMessage) {
    if (reference == null) {
      throw new IllegalArgumentException(String.valueOf(errorMessage));
    }
    return reference;
  }

  /**
   * Ensures that an object reference passed as a parameter to the calling method is not null.
   *
   * @param reference an object reference
   * @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
   */

View on GitHub (pinned to 12126d8942)

Solutions

1. Supply the required non-null value before the call.
2. Read the exception message to identify which parameter was null.
3. Prefer the template/message overloads for better diagnostics.

Example fix

// before
Preconditions.checkArgumentNotNull(name); // message lost
// after
Preconditions.checkNotNull(name, "name must not be null");

if (ref == null) throw new IllegalArgumentException("meaningful message here");

null

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

When it happens

Trigger: Passing null to an API that validates with checkArgumentNotNull(ref, errorMessage); the message parameter itself may be null (then the exception message is "null").

Common situations: Missing configuration values (null connection strings, null bucket names) reaching Beam APIs during pipeline construction.

Related errors

• IllegalArgumentException
• lenientFormat(errorMessageTemplate, errorMessageArgs)
• 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/1e6f4d9153996a13. Report an issue: GitHub.