apache/beam · error · RuntimeError

Could not complete the query request

Error message

Could not complete the query request: {query}. {e}

What it means

_execute_query() wraps RuntimeError from the BigQuery client's query-and-result call, re-raising with the query text. This indicates the query request could not be completed (client/runtime failure), distinct from a BadRequest (malformed query).

Solutions

1. Retry the enrichment (the error is often transient)
2. Check job logs in BigQuery console for the underlying cause
3. Verify BigQuery client configuration/credentials and network access
4. Catch RuntimeError and apply a fallback enrichment strategy

Example fix

// before
result = handler(row)
// after
try:
    result = handler(row)
except RuntimeError:
    result = fallback_lookup(row)

try:
    out = handler(row)
except RuntimeError as e:
    logger.warning('Transient BigQuery failure, retrying: %s', e)
    out = retry(lambda: handler(row), attempts=3)

When it happens

Trigger: The BigQuery client raises RuntimeError during query execution — e.g. request interrupted, client-side runtime failure in query_and_results — propagating through __call__.

Common situations: Transient BigQuery client failures, job timeouts surfacing as RuntimeError, misconfigured client/session.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• A BigQuery table or a query must be specified
• A function must be provided to convert the input type into…
• A schema is required in order to prepare rows for writing…
• A schema must be provided when writing to BigQuery using…
• Bigquery dependencies are not installed.

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/bigquery.py:187

    self.client = bigquery.Client(project=self.project, **self.kwargs)

  def _execute_query(self, query: str):
    try:
      results = self.client.query(query=query).result()
      row_list = [dict(row.items()) for row in results]
      if not row_list:
        return None
      if self._batching_kwargs:
        return row_list
      else:
        return row_list[0]
    except BadRequest as e:
      raise BadRequest(
          f'Could not execute the query: {query}. Please check if '
          f'the query is properly formatted and the BigQuery '
          f'table exists. {e}')
    except RuntimeError as e:
      raise RuntimeError(f"Could not complete the query request: {query}. {e}")

  def create_row_key(self, row: beam.Row):
    if self.condition_value_fn:
      return tuple(self.condition_value_fn(row))
    if self.fields:
      row_dict = row._asdict()
      return (tuple(row_dict[field] for field in self.fields))
    raise ValueError("Either fields or condition_value_fn must be specified")

  def __call__(self, request: Union[beam.Row, list[beam.Row]], *args, **kwargs):
    if isinstance(request, list):
      values = []
      responses = []
      requests_map: dict[Any, list[beam.Row]] = defaultdict(list)
      batch_size = len(request)
      raw_query = self.query_template
      if batch_size > 1:
        batched_condition_template = ' or '.join(

View on GitHub (pinned to 12126d8942)