{"record":{"id":"d8f011bc1a630dd1","repo":"infiniflow/ragflow","slug":"failed-to-create-bigquery-client-exc","errorCode":null,"errorMessage":"Failed to create BigQuery client: {exc}","messagePattern":"Failed to create BigQuery client: (.+?)","errorType":"validation","errorClass":"ConnectorValidationError","httpStatus":null,"severity":"error","filePath":"common/data_source/bigquery_connector.py","lineNumber":192,"sourceCode":"            raise ConnectorValidationError(\"BigQuery client not installed. Please install google-cloud-bigquery.\")\n\n        service_account_info = self._credentials.get(\"service_account_info\")\n        if not service_account_info:\n            raise ConnectorMissingCredentialError(\"BigQuery credentials not loaded.\")\n\n        try:\n            creds = service_account.Credentials.from_service_account_info(service_account_info)\n        except Exception as exc:\n            raise ConnectorValidationError(f\"Failed to build BigQuery credentials: {exc}\")\n\n        try:\n            self._client = bigquery.Client(\n                project=self.project_id or None,\n                credentials=creds,\n                location=self.location or None,\n            )\n        except Exception as exc:\n            raise ConnectorValidationError(f\"Failed to create BigQuery client: {exc}\")\n\n        return self._client\n\n    # ------------------------------------------------------------------ #\n    # Query construction\n    # ------------------------------------------------------------------ #\n    def _build_base_query(self) -> str:\n        \"\"\"Return the single base query (custom query takes precedence over table mode).\"\"\"\n        if self.query:\n            return self.query.rstrip(\";\")\n        if self.dataset_id and self.table_id:\n            return f\"SELECT * FROM `{self.project_id}.{self.dataset_id}.{self.table_id}`\"\n        raise ConnectorValidationError(\"BigQuery requires either a custom query or both dataset_id and table_id.\")\n\n    @staticmethod\n    def _wrap_query(base_query: str, select_clause: str = \"*\") -> str:\n        return f\"SELECT {select_clause} FROM ({base_query}) AS ragflow_src\"\n","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/bigquery_connector.py#L174-L210","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check exc.__cause__ first — it distinguishes parameter errors from network/transport errors","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","For network causes in containers: ensure CA certificates are installed and HTTPS egress to bigquery.googleapis.com is allowed","Upgrade google-cloud-bigquery — some versions had stricter location validation"],"exampleFix":"# before\nconnector = BigQueryConnector(project_id=\"my project\", location=\"us-central1-a\", ...)\n\n# after\nconnector = BigQueryConnector(project_id=\"my-project\", location=\"us-central\", ...)\n# or omit location if unsure","handlingStrategy":"try-catch","validationCode":"import re\ndef validate_bq_client_params(project_id: str | None, location: str | None) -> None:\n    if project_id is not None and not re.fullmatch(r\"[a-z][a-z0-9-]{4,28}[a-z0-9]\", project_id.strip()):\n        raise ValueError(f\"invalid GCP project id: {project_id!r}\")\n    if location is not None and not re.fullmatch(r\"[a-z0-9]+(-[a-z0-9]+)?\", location.strip()):\n        raise ValueError(f\"invalid BigQuery location: {location!r}\")","typeGuard":"def is_valid_gcp_project_id(pid: str | None) -> bool:\n    return pid is None or bool(re.fullmatch(r\"[a-z][a-z0-9-]{4,28}[a-z0-9]\", pid))","tryCatchPattern":"try:\n    connector.validate_connector_settings()\nexcept ConnectorValidationError as e:\n    cause = e.__cause__\n    if \"Failed to create BigQuery client\" in str(e):\n        logger.error(\"client construction failed: %s\", cause)\n        if is_param_error(cause):\n            raise ConfigError(\"check project_id / location values\") from e\n        raise TransientError(\"network/transport during client init; retry\") from e\n    raise","preventionTips":["Validate project_id and location formats at config time, not at client construction","In air-gapped/containerized deployments, verify CA certs and egress to bigquery.googleapis.com before deploying","Always inspect __cause__: parameter errors are permanent, transport errors may be transient"],"tags":["bigquery","gcp","client","configuration","network"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}