apache/beam · error · ValueError

Encountered unsupported parameter(s) in read_gbq: {kwargs.ke

Error message

Encountered unsupported parameter(s) in read_gbq: {kwargs.keys()!r}

What it means

read_gbq in the Beam DataFrame API accepts only its documented parameters (table, dataset, project_id, use_bqstorage_api). Any extra keyword arguments — e.g. pandas-style options — trigger this ValueError listing the unsupported keys, since the deferred BigQuery reader implements only a subset of the pandas-gbq signature.

Source

Thrown at sdks/python/apache_beam/dataframe/io.py:82

  :class:`~apache_beam.dataframe.frames.DeferredDataFrame.

  Args:
    table (str): Please specify a table. This can be done in the format
      'PROJECT:dataset.table' if one would not wish to utilize
      the parameters below.
    dataset (str): Please specify the dataset
      (can omit if table was specified as 'PROJECT:dataset.table').
    project_id (str): Please specify the project ID
      (can omit if table was specified as 'PROJECT:dataset.table').
    use_bqstorage_api (bool): If you would like to utilize
      the BigQuery Storage API in ReadFromBigQuery, please set
      this flag to true. Otherwise, please set flag
      to false or leave it unspecified.
      """
  if table is None:
    raise ValueError("Please specify a BigQuery table to read from.")
  elif len(kwargs) > 0:
    raise ValueError(
        f"Encountered unsupported parameter(s) in read_gbq: {kwargs.keys()!r}"
        "")
  return _ReadGbq(table, dataset, project_id, use_bqstorage_api)


@frame_base.with_docs_from(pd)
def read_csv(path, *args, splittable=False, binary=True, **kwargs):
  """If your files are large and records do not contain quoted newlines, you may
  pass the extra argument ``splittable=True`` to enable dynamic splitting for
  this read on newlines. Using this option for records that do contain quoted
  newlines may result in partial records and data corruption."""
  if 'nrows' in kwargs:
    raise ValueError('nrows not yet supported')
  filename_column = kwargs.pop('filename_column', None)
  return _ReadFromPandas(
      pd.read_csv,
      path,
      args,

View on GitHub (pinned to 12126d8942)

Solutions

  1. Remove all kwargs except table, dataset, project_id, use_bqstorage_api from the call.
  2. If you need SQL-level querying or advanced options, use apache_beam.io.gcp.bigquery.ReadFromBigQuery instead.
  3. Check parameter spelling against the read_gbq signature in sdks/python/apache_beam/dataframe/io.py.

Example fix

// before
read_gbq(table='t', dataset='d', query='SELECT 1')
// after
read_gbq(table='t', dataset='d')  # or ReadFromBigQuery(query='SELECT 1')
Defensive patterns

Strategy: validation

Validate before calling

ALLOWED = {'table', 'dataset', 'project_id', 'use_bqstorage_api'}
extra = set(kwargs) - ALLOWED
if extra:
    raise ValueError(f'Unsupported read_gbq kwargs: {extra}')

Try / catch

try:
    df = read_gbq(**opts)
except ValueError:
    opts = {k: v for k, v in opts.items() if k in ALLOWED}
    df = read_gbq(**opts)

Prevention

When it happens

Trigger: Calling read_gbq(table=..., query=...), read_gbq(..., location='EU'), or passing pandas-gbq style options (reauth, dialect, credentials) that the Beam connector does not accept.

Common situations: Migrating code from pandas.read_gbq or google-cloud-bigquery to Beam's read_gbq and keeping old kwargs; typos in parameter names (e.g. projectid vs project_id).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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