What causes "Namespace cannot be empty." in apache/beam?

Pass a non-empty namespace to the metrics publisher configuration

apache/beam · error · ValueError

Namespace cannot be empty.

Error message

Namespace cannot be empty.

What it means

BigQueryClient validates that a namespace was provided before creating/looking up the BigQuery table, since the namespace doubles as the table name. An empty namespace string makes table addressing impossible, so _get_or_create_table raises immediately during client construction.

Solutions

Pass a non-empty namespace to the metrics publisher configuration
Check the pipeline option/flag that feeds the namespace and make it required or set a sensible default
Validate namespace at pipeline startup before constructing BigQueryClient

Example fix

// before
BigQueryClient(bq_schemas, dataset, namespace='')
// after
BigQueryClient(bq_schemas, dataset, namespace='load-test-2024-09')

Defensive patterns

Strategy: validation

Validate before calling

if not namespace or not isinstance(namespace, str):
    raise ValueError('namespace must be a non-empty string')

Type guard

def valid_namespace(ns):
    return isinstance(ns, str) and len(ns) > 0

Try / catch

try:
    client = BigQueryClient(schemas, dataset, namespace)
except ValueError:
    _LOGGER.error('Namespace missing; pass --namespace')
    raise

Prevention

Make the namespace pipeline option required
Validate all metrics options at pipeline startup
Use a naming convention like test-name + date

When it happens

Trigger: Instantiating BigQueryClient (via __init__ -> _get_or_create_table) with namespace='' or a namespace that resolves to an empty string, e.g. from an unset pipeline option.

Common situations: Forgot to pass --namespace (or the metrics namespace option) when launching a load-test pipeline; option read with default '' instead of required value.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/testing/load_tests/load_test_metrics_utils.py:488

  """A :class:`BigQueryClient` publishes collected metrics to
  BigQuery output."""
  def __init__(self, project_name, table, dataset, bq_schema=None):
    self.schema = bq_schema
    self._namespace = table
    self._client = bigquery.Client(project=project_name)
    self._schema_names = self._get_schema_names()
    schema = self._prepare_schema()
    self._get_or_create_table(schema, dataset)

  def _get_schema_names(self):
    return [schema['name'] for schema in self.schema]

  def _prepare_schema(self):
    return [SchemaField(**row) for row in self.schema]

  def _get_or_create_table(self, bq_schemas, dataset):
    if self._namespace == '':
      raise ValueError('Namespace cannot be empty.')

    dataset = self._get_dataset(dataset)
    table_ref = dataset.table(self._namespace)

    try:
      self._bq_table = self._client.get_table(table_ref)
    except NotFound:
      table = bigquery.Table(table_ref, schema=bq_schemas)
      self._bq_table = self._client.create_table(table)

  def _update_schema(self):
    table_schema = self._bq_table.schema
    if self.schema and len(table_schema) != self.schema:
      self._bq_table.schema = self._prepare_schema()
      self._bq_table = self._client.update_table(self._bq_table, ["schema"])

  def _get_dataset(self, dataset_name):
    bq_dataset_ref = self._client.dataset(dataset_name)

View on GitHub (pinned to 12126d8942)