apache/beam · error · ValueError

project and location must be None if api_key is set

Error message

project and location must be None if api_key is set

What it means

Raised by the Gemini model handler __init__ when an api_key is provided together with a project and/or location. API-key authentication uses the Gemini Developer API, which does not take GCP project/location; those are only for Vertex AI.

Solutions

Pass project=None and location=None when authenticating with api_key.
Remove api_key and supply both project and location if Vertex AI is the intended backend.
Read project/location from config conditionally: only when no api_key is present.

Example fix

// before
GeminiModelHandler(model_name='gemini-2.0-flash', api_key=key, project='my-proj', location='us-central1')
// after
GeminiModelHandler(model_name='gemini-2.0-flash', api_key=key)

Defensive patterns

Strategy: validation

Validate before calling

if api_key and (project or location):
    raise ValueError('drop project/location when using api_key')

Prevention

Make auth mode explicit: api_key XOR (project, location), never both.
Conditionally build constructor kwargs based on which credential is present.

When it happens

Trigger: Constructing GeminiModelHandler(api_key='...', project='my-proj') or GeminiModelHandler(api_key='...', location='us-central1').

Common situations: Config templates that always populate project/location while also injecting an API key from a secret; switching between Vertex and Developer API auth without removing the other fields.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/ml/inference/gemini_inference.py:190

    if max_batch_size is not None:
      self._batching_kwargs["max_batch_size"] = max_batch_size
    if max_batch_duration_secs is not None:
      self._batching_kwargs["max_batch_duration_secs"] = max_batch_duration_secs
    if max_batch_weight is not None:
      self._batching_kwargs["max_batch_weight"] = max_batch_weight
    if element_size_fn is not None:
      self._batching_kwargs['element_size_fn'] = element_size_fn
    if batch_length_fn is not None:
      self._batching_kwargs['length_fn'] = batch_length_fn
    if batch_bucket_boundaries is not None:
      self._batching_kwargs['bucket_boundaries'] = batch_bucket_boundaries

    self.model_name = model_name
    self.request_fn = request_fn

    if api_key:
      if project or location:
        raise ValueError("project and location must be None if api_key is set")
      self.api_key = api_key
      self.use_vertex = False
    else:
      if project is None or location is None:
        raise ValueError(
            "project and location must both be provided if api_key is None")
      self.project = project
      self.location = location
      self.use_vertex = True

    self.use_vertex_flex_api = use_vertex_flex_api

    super().__init__(
        namespace='GeminiModelHandler',
        retry_filter=_retry_on_appropriate_service_error,
        **kwargs)

  def batch_elements_kwargs(self):

View on GitHub (pinned to 12126d8942)