infiniflow/ragflow · error · ConnectorValidationError

Failed to create BigQuery client: {exc}

Error message

Failed to create BigQuery client: {exc}

What it means

Final construction step of _get_client: bigquery.Client(...) itself threw, and the exception is wrapped as ConnectorValidationError. Credentials built successfully; the failure is in project/location parameters or low-level client setup. The original exception is chained for diagnosis.

Source

Thrown at common/data_source/bigquery_connector.py:192

            raise ConnectorValidationError("BigQuery client not installed. Please install google-cloud-bigquery.")

        service_account_info = self._credentials.get("service_account_info")
        if not service_account_info:
            raise ConnectorMissingCredentialError("BigQuery credentials not loaded.")

        try:
            creds = service_account.Credentials.from_service_account_info(service_account_info)
        except Exception as exc:
            raise ConnectorValidationError(f"Failed to build BigQuery credentials: {exc}")

        try:
            self._client = bigquery.Client(
                project=self.project_id or None,
                credentials=creds,
                location=self.location or None,
            )
        except Exception as exc:
            raise ConnectorValidationError(f"Failed to create BigQuery client: {exc}")

        return self._client

    # ------------------------------------------------------------------ #
    # Query construction
    # ------------------------------------------------------------------ #
    def _build_base_query(self) -> str:
        """Return the single base query (custom query takes precedence over table mode)."""
        if self.query:
            return self.query.rstrip(";")
        if self.dataset_id and self.table_id:
            return f"SELECT * FROM `{self.project_id}.{self.dataset_id}.{self.table_id}`"
        raise ConnectorValidationError("BigQuery requires either a custom query or both dataset_id and table_id.")

    @staticmethod
    def _wrap_query(base_query: str, select_clause: str = "*") -> str:
        return f"SELECT {select_clause} FROM ({base_query}) AS ragflow_src"

View on GitHub (pinned to 554fb1133a)

Solutions

  1. Check exc.__cause__ first — it distinguishes parameter errors from network/transport errors
  2. Verify project_id is the exact GCP project id (no spaces/quotes) and location is a valid BigQuery region (e.g. 'US', 'EU', 'asia-east1') or leave it empty
  3. For network causes in containers: ensure CA certificates are installed and HTTPS egress to bigquery.googleapis.com is allowed
  4. Upgrade google-cloud-bigquery — some versions had stricter location validation

Example fix

# before
connector = BigQueryConnector(project_id="my project", location="us-central1-a", ...)

# after
connector = BigQueryConnector(project_id="my-project", location="us-central", ...)
# or omit location if unsure
Defensive patterns

Strategy: try-catch

Validate before calling

import re
def validate_bq_client_params(project_id: str | None, location: str | None) -> None:
    if project_id is not None and not re.fullmatch(r"[a-z][a-z0-9-]{4,28}[a-z0-9]", project_id.strip()):
        raise ValueError(f"invalid GCP project id: {project_id!r}")
    if location is not None and not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)?", location.strip()):
        raise ValueError(f"invalid BigQuery location: {location!r}")

Type guard

def is_valid_gcp_project_id(pid: str | None) -> bool:
    return pid is None or bool(re.fullmatch(r"[a-z][a-z0-9-]{4,28}[a-z0-9]", pid))

Try / catch

try:
    connector.validate_connector_settings()
except ConnectorValidationError as e:
    cause = e.__cause__
    if "Failed to create BigQuery client" in str(e):
        logger.error("client construction failed: %s", cause)
        if is_param_error(cause):
            raise ConfigError("check project_id / location values") from e
        raise TransientError("network/transport during client init; retry") from e
    raise

Prevention

When it happens

Trigger: bigquery.Client(project=..., credentials=..., location=...) raises — commonly a malformed project_id (e.g. empty string vs None handled via 'or None', but a bogus non-None value fails), an invalid location string, or a google-auth/transport error during client construction in restricted environments (no certifi store, proxy misconfig).

Common situations: Typo'd project_id ('my-project ' with whitespace, or the project number vs id confusion), an unsupported location value from config, or air-gapped environments where client construction attempts to reach metadata/token endpoints and fails.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/d8f011bc1a630dd1. Report an issue: GitHub.