apache/beam · error · ValueError

Instance connection URI cannot be empty

Error message

Instance connection URI cannot be empty

What it means

The Cloud SQL enrichment handler's connection config is a dataclass that validates in __post_init__ that instance_connection_uri is non-empty. This URI (format 'project:region:instance') is required for the Cloud SQL Python Connector to locate and open a database connection. Construction fails fast with ValueError when it is empty or missing.

Solutions

  1. Pass a non-empty instance_connection_uri in 'project:region:instance' format.
  2. Verify the pipeline option / env var feeding the value is actually populated at runtime.
  3. Add a pre-construction assertion that the URI is set before building the config.

Example fix

# before
config = CloudSQLConnectionConfig(instance_connection_uri="", query_config=qcfg)
# after
config = CloudSQLConnectionConfig(instance_connection_uri="my-project:us-central1:my-instance", query_config=qcfg)
Defensive patterns

Strategy: validation

When it happens

Trigger: Calling CloudSQLConnectionConfig(...) without instance_connection_uri, or passing "" or None. Also occurs when the value is sourced from pipeline options or env vars that were not set.

Common situations: Building the config from YAML/JSON or env vars with a missing key; typos in the field name so the empty default is used; copying example code and deleting the URI line.

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/62aa0d7797f003b9. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/cloudsql.py:150

        db_id: Database identifier/name.
        refresh_strategy: Strategy for refreshing connection (default: LAZY).
        connector_kwargs: Additional keyword arguments for the
          Cloud SQL Python Connector. Enables forward compatibility.
        connect_kwargs: Additional keyword arguments for the client connect
          method. Enables forward compatibility.
    """
  db_adapter: DatabaseTypeAdapter
  instance_connection_uri: str
  user: str = field(default_factory=str)
  password: str = field(default_factory=str)
  db_id: str = field(default_factory=str)
  refresh_strategy: RefreshStrategy = RefreshStrategy.LAZY
  connector_kwargs: dict[str, Any] = field(default_factory=dict)
  connect_kwargs: dict[str, Any] = field(default_factory=dict)

  def __post_init__(self):
    if not self.instance_connection_uri:
      raise ValueError("Instance connection URI cannot be empty")

  def get_connector_handler(self) -> Callable[[], DBAPIConnection]:
    """Returns a function that creates a new database connection.

      The returned connector function creates database connections that should
      be properly closed by the caller when no longer needed.
      """
    cloudsql_client = CloudSQLConnector(
        refresh_strategy=self.refresh_strategy, **self.connector_kwargs)

    cloudsql_connector = lambda: cloudsql_client.connect(
        instance_connection_string=self.instance_connection_uri, driver=self.
        db_adapter.value, user=self.user, password=self.password, db=self.db_id,
        **self.connect_kwargs)

    return cloudsql_connector

  def get_db_url(self) -> str:

View on GitHub (pinned to 12126d8942)