apache/beam · error · ValueError

Database host cannot be empty

Error message

Database host cannot be empty

What it means

The database-specific connection config dataclass (host/user/password/db_id based) validates in __post_init__ that host is non-empty. With the Cloud SQL Python Connector, host carries the instance connection URI, so an empty host makes connection impossible.

Solutions

  1. Set host to the instance connection URI ('project:region:instance') when using the Cloud SQL connector.
  2. Verify the config kwargs match the dataclass field names exactly.
  3. Validate required fields before constructing the config.

Example fix

# before
config = QueryCloudSQLConnectionConfig(host="", db_adapter=DatabaseTypeAdapter.POSTGRESQL, ...)
# after
config = QueryCloudSQLConnectionConfig(host="my-project:us-central1:my-instance", db_adapter=DatabaseTypeAdapter.POSTGRESQL, ...)
Defensive patterns

Strategy: validation

When it happens

Trigger: Constructing a config such as QueryCloudSQLConnectionConfig or TableCloudSQLConnectionConfig without host, or with host="" or None.

Common situations: Assuming a localhost default exists; options/env not plumbed through to the worker; editing a shared config template and dropping the host field.

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/6b693f1786bec3b4. Report an issue: GitHub.

Appendix: source

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

        host: Hostname or IP address of the database server.
        port: Port number for the database connection.
        user: Username for authentication.
        password: Password for authentication.
        db_id: Database identifier/name.
        connect_kwargs: Additional keyword arguments for the client connect
          method. Enables forward compatibility.
    """
  db_adapter: DatabaseTypeAdapter
  host: str
  port: int
  user: str = field(default_factory=str)
  password: str = field(default_factory=str)
  db_id: str = field(default_factory=str)
  connect_kwargs: dict[str, Any] = field(default_factory=dict)

  def __post_init__(self):
    if not self.host:
      raise ValueError("Database host 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.
      """
    if self.db_adapter == DatabaseTypeAdapter.POSTGRESQL:
      return lambda: pg8000.connect(
          host=self.host, port=self.port, database=self.db_id, user=self.user,
          password=self.password, **self.connect_kwargs)
    elif self.db_adapter == DatabaseTypeAdapter.MYSQL:
      return lambda: pymysql.connect(
          host=self.host, port=self.port, database=self.db_id, user=self.user,
          password=self.password, **self.connect_kwargs)
    elif self.db_adapter == DatabaseTypeAdapter.SQLSERVER:
      return lambda: pytds.connect(
          dsn=self.host, port=self.port, database=self.db_id, user=self.user,

View on GitHub (pinned to 12126d8942)