infiniflow/ragflow · error · ConnectorValidationError

BigQuery client not installed. Please install google-cloud-b

Error message

BigQuery client not installed. Please install google-cloud-bigquery.

What it means

Raised by _get_client when the optional google-cloud-bigquery / google-auth imports failed at module load (the module sets bigquery/service_account to None on ImportError). It is a ConnectorValidationError, not a credential error: the runtime environment lacks the client library, so no credential or network fix will help.

Source

Thrown at common/data_source/bigquery_connector.py:174

            try:
                service_account_info = json.loads(raw)
            except json.JSONDecodeError as exc:
                raise ConnectorMissingCredentialError(f"BigQuery: service_account_json is not valid JSON: {exc}")
        elif isinstance(raw, dict):
            service_account_info = raw
        else:
            raise ConnectorMissingCredentialError("BigQuery: service_account_json must be a JSON string or object")

        self._credentials = {"service_account_info": service_account_info}
        return None

    def _get_client(self):
        """Create and cache a BigQuery client from the loaded service account."""
        if self._client is not None:
            return self._client

        if bigquery is None or service_account is None:
            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}")

View on GitHub (pinned to 554fb1133a)

Solutions

1. pip install google-cloud-bigquery in the environment that runs the connector
2. Verify with: python -c 'from google.cloud import bigquery; from google.oauth2 import service_account'
3. If using docker, rebuild the image so the dependency layer is present in the deployed image, not just the build stage
4. Pin compatible versions if google-auth conflicts with other libraries (check pip check)

Example fix

# before: ImportError swallowed at module import, then
connector._get_client()  # -> ConnectorValidationError

# after
pip install google-cloud-bigquery
python -c "from google.cloud import bigquery; from google.oauth2 import service_account; print('ok')"
connector._get_client()

def require_bigquery_deps():
    try:
        from google.cloud import bigquery  # noqa: F401
        from google.oauth2 import service_account  # noqa: F401
    except ImportError as e:
        raise RuntimeError(
            "google-cloud-bigquery is required for the BigQuery connector; "
            "install it in the runtime environment"
        ) from e

def bigquery_available() -> bool:
    try:
        from google.cloud import bigquery  # noqa: F401
        from google.oauth2 import service_account  # noqa: F401
        return True
    except ImportError:
        return False

try:
    connector.validate_connector_settings()
except ConnectorValidationError as e:
    if "not installed" in str(e):
        raise DeploymentError("install google-cloud-bigquery in the runtime image") from e
    raise

When it happens

Trigger: Deploying the connector in an image/venv where 'google-cloud-bigquery' (or its google-auth dependency) is not installed or failed to import; the first _get_client call (during validate or first query) then hits this branch.

Common situations: Slim production images that omit optional connector deps, dependency-resolution conflicts breaking google-auth transitive imports, or running from a different virtualenv than the one where the package was installed.

Related errors

• paramiko is required for the SSH sandbox provider. Install t
• BigQuery: missing service_account_json
• BigQuery: service_account_json is not valid JSON: {exc}
• BigQuery: service_account_json must be a JSON string or obje
• BigQuery credentials not loaded.

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