apache/beam · error · IllegalArgumentException

IllegalArgumentException

Error message

IllegalArgumentException

What it means

Beam's own Preconditions.checkArgumentNotNull throws IllegalArgumentException when the given reference is null, providing a null-check helper with a return value for inline assignment. It mirrors Guava's checkNotNull but signals an argument problem rather than a value problem.

Source

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

 */
@Internal
@SuppressWarnings({
  "nullness" // TODO(https://github.com/apache/beam/issues/20497)
})
public class Preconditions {
  /**
   * Ensures that an object reference passed as a parameter to the calling method is not null.
   *
   * @param reference an object reference
   * @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) {
    if (reference == null) {
      throw new IllegalArgumentException();
    }
    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) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the argument is non-null before calling the API.
2. Add an explicit null check or default value at the call site.
3. Use the overload with an error message to get a more diagnosable failure.

Example fix

// before
sink.writeToFile(null);
// after
checkState(path != null, "output path must be set");
sink.writeToFile(path);

if (value == null) { throw new IllegalArgumentException("value must not be null"); }

null

try { apiCall(value); } catch (IllegalArgumentException e) { /* null argument rejected */ }

When it happens

Trigger: Passing null as an argument to any API that validates it with Preconditions.checkArgumentNotNull, e.g. constructor or method parameters that must be non-null.

Common situations: Optional/missing configuration passed into transforms or resources; nullable method returns fed straight into Beam APIs.

Related errors

• String.valueOf(errorMessage)
• 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/5584d8a2aff96f87. Report an issue: GitHub.