apache/beam · error · NullPointerException

GeminiModelParameters must not be null

Error message

GeminiModelParameters must not be null

What it means

GeminiModelHandler.createClient requires a non-null GeminiModelParameters object to configure either an API-key client or a Vertex AI client. Passing null immediately throws this NullPointerException before any client setup. It is an explicit fail-fast guard rather than an incidental NPE.

Source

Thrown at sdks/java/ml/inference/gemini/src/main/java/org/apache/beam/sdk/ml/inference/gemini/GeminiModelHandler.java:45

/**
 * Model handler for Google Gemini API inference requests.
 *
 * <p>This handler manages communication with Google's Gemini API, including client initialization,
 * request formatting, and response parsing. It allows executing a custom {@link
 * GeminiRequestFunction} against a batch of inputs.
 */
@SuppressWarnings("nullness")
public class GeminiModelHandler<InputT extends BaseInput, OutputT extends BaseResponse>
    implements BaseModelHandler<GeminiModelParameters<InputT, OutputT>, InputT, OutputT> {

  private transient Client client;
  private GeminiModelParameters<InputT, OutputT> modelParameters;

  @Override
  public void createClient(GeminiModelParameters<InputT, OutputT> parameters) {
    if (parameters == null) {
      throw new NullPointerException("GeminiModelParameters must not be null");
    }
    this.modelParameters = parameters;

    // Configure client based on vertex or API key
    if (parameters.getApiKey() != null) {
      if (parameters.getProject() != null || parameters.getLocation() != null) {
        throw new IllegalArgumentException("Project and location must be null if API key is set");
      }
      this.client = Client.builder().apiKey(parameters.getApiKey()).build();
    } else {
      Client.Builder builder = Client.builder();
      if (parameters.getProject() != null && parameters.getLocation() != null) {
        builder.vertexAI(true).project(parameters.getProject()).location(parameters.getLocation());
      } else if (parameters.getProject() != null || parameters.getLocation() != null) {
        throw new IllegalArgumentException(
            "Project and location must both be provided if one is provided");
      }
      this.client = builder.build();

View on GitHub (pinned to 12126d8942)

Solutions

1. Provide GeminiModelParameters via the builder (withModelParameters / equivalent) before applying the handler.
2. Ensure at least an apiKey or both project+location are present in the parameters object.
3. Add a null/emptiness check on your configuration object before instantiating the handler.

Example fix

// before
handler.createClient(null);
// after
GeminiModelParameters<InputT, OutputT> p = GeminiModelParameters.<InputT, OutputT>builder().setApiKey(key).build();
handler.createClient(p);

checkNotNull(parameters, "GeminiModelParameters must be configured before createClient");

boolean paramsReady(GeminiModelParameters<?,?> p) { return p != null && (p.getApiKey() != null || (p.getProject() != null && p.getLocation() != null)); }

try { handler.createClient(params); } catch (NullPointerException e) { throw new IllegalStateException("GeminiModelParameters missing", e); }

When it happens

Trigger: Calling createClient(null) directly, or configuring the handler such that its parameters field is never set (e.g. forgetting withModelParameters(...) during setup, which tests like testNullParameters exercise).

Common situations: Programmatic handler construction where the builder chain was interrupted or parameters were conditionally skipped; reflection-based or serialized handler instances missing parameters.

Related errors

• lenientFormat(errorMessageTemplate, p1, p2)
• Can't compare %s with NULL
• Staleness value cannot be empty when MAX_STALENESS or EXACT_
• Time unit cannot be null when MAX_STALENESS or EXACT_STALENE
• Timestamp cannot be null when READ_TIMESTAMP or MIN_READ_TIM

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