apache/beam · error · NotFound

GCP BigTable cluster `%s:%s:%s` not found.

Error message

GCP BigTable cluster `%s:%s:%s` not found.

What it means

The BigTable enrichment handler catches google.cloud.bigtable NotFound and re-raises it with the full resource path `project:instance:table`, indicating Bigtable returned that the table (or its instance/cluster) does not exist or is not accessible.

Source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/bigtable.py:149

            if self._include_timestamp:
              response_dict[cf_id][col_id.decode(self._encoding)] = [
                  (v.value.decode(self._encoding), v.timestamp) for v in col_v
              ]
            else:
              response_dict[cf_id][col_id.decode(
                  self._encoding)] = col_v[0].value.decode(self._encoding)
      elif self._exception_level == ExceptionLevel.WARN:
        _LOGGER.warning(
            'no matching row found for row_key: %s '
            'with row_filter: %s' % (row_key_str, self._row_filter))
      elif self._exception_level == ExceptionLevel.RAISE:
        raise ValueError(
            'no matching row found for row_key: %s '
            'with row_filter=%s' % (row_key_str, self._row_filter))
    except KeyError:
      raise KeyError('row_key %s not found in input PCollection.' % row_key_str)
    except NotFound:
      raise NotFound(
          'GCP BigTable cluster `%s:%s:%s` not found.' %
          (self._project_id, self._instance_id, self._table_id))
    except Exception as e:
      raise e

    return request, beam.Row(**response_dict)

  def __exit__(self, exc_type, exc_val, exc_tb):
    """Clean the instantiated BigTable client."""
    self.client = None
    self.instance = None
    self._table = None

  def get_cache_key(self, request: beam.Row) -> str:
    """Returns a string formatted with row key since it is unique to
    a request made to `Bigtable`."""
    if self._row_key_fn:
      return "row_key: %s" % str(self._row_key_fn(request))

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify the project/instance/table IDs exist via `gcloud bigtable instances tables list`
2. Check credentials have bigtable.tables.readAccess on the target table
3. Recreate the table if it was deleted, or point the handler at the right environment

Example fix

// before
BigTableEnrichmentHandler(project_id='proj', instance_id='prod-inst', table_id='enrich')
// after
BigTableEnrichmentHandler(project_id='proj', instance_id='dev-inst', table_id='enrich')  # table verified to exist

from google.cloud import bigtable
client = bigtable.Client(project=project_id)
inst = client.instance(instance_id)
if not inst.exists():
    raise ValueError(f'instance {instance_id} missing')
if not inst.table(table_id).exists():
    raise ValueError(f'table {table_id} missing')

try:
    enriched = rows | Enrichment(handler)
except NotFound as e:
    log.error('verify project:instance:table exists and credentials have access: %s', e)
    raise

When it happens

Trigger: Calling BigTableEnrichmentHandler.__call__ where self._project_id/_instance_id/_table_id point to a nonexistent or deleted table/instance, or the caller lacks permission so Bigtable reports NotFound.

Common situations: Typos in instance/table IDs; running against the wrong project; the table was deleted or not yet created in a new environment; cross-project access without correct credentials.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• no matching row found for row_key: %s with row_filter=%s
• Vertex AI Feature Store %s does not exists in %s
• Unexpected mutation
• query.project cannot be empty
• query cannot be empty

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