What causes "BigQuery validation failed: {exc}" in infiniflow/ragflow?

Read the embedded {exc} text — it carries the root cause (auth vs permission vs SQL vs network)

infiniflow/ragflow · error · ConnectorValidationError

BigQuery validation failed: {exc}

Error message

BigQuery validation failed: {exc}

What it means

Catch-all in validate_connector_settings: any exception that is not already a ConnectorValidationError/ConnectorMissingCredentialError (e.g. auth failures, permission errors, network errors, invalid SQL from the dry-run) is re-raised wrapped as ConnectorValidationError with the original message.

Source

Thrown at common/data_source/bigquery_connector.py:638

            schema_columns = {field.name for field in schema}

            required = set(self.content_columns)
            optional = set(self.metadata_columns)
            if self.id_column:
                optional.add(self.id_column)
            if self.timestamp_column:
                optional.add(self.timestamp_column)

            missing = (required | optional) - schema_columns
            if missing:
                raise ConnectorValidationError(f"BigQuery configured columns not found in schema: {', '.join(sorted(missing))}")

            if self.timestamp_column:
                self._resolve_cursor_param_type()
        except (ConnectorValidationError, ConnectorMissingCredentialError):
            raise
        except Exception as exc:
            raise ConnectorValidationError(f"BigQuery validation failed: {exc}")

View on GitHub (pinned to 554fb1133a)

Solutions

Read the embedded {exc} text — it carries the root cause (auth vs permission vs SQL vs network)
Fix the underlying issue: valid credentials with BigQuery roles, runnable query, network access to bigquery.googleapis.com
Re-run validate_connector_settings() after each fix

Defensive patterns

Strategy: try-catch

Validate before calling

# Smoke-test prerequisites before validate: auth, network, query
from google.auth import default as gdefault  # or service_account
try:
    import socket; socket.create_connection(("bigquery.googleapis.com", 443), timeout=5)
except OSError:
    raise RuntimeError("no network path to BigQuery")

Try / catch

try:
    conn.validate_connector_settings()
except ConnectorValidationError as e:
    root = str(e).removeprefix("BigQuery validation failed: ")
    log_and_alert(root)  # root carries the original auth/permission/SQL error
    if "403" in root: fix_iam_roles()
    elif "Syntax error" in root: fix_query()
    else: raise

Prevention

Treat the wrapped message as the source of truth; never string-match the generic prefix
Run a SELECT 1 dry-run in CI against the connector's service account
Grant the service account roles/bigquery.jobUser plus dataViewer on the dataset

When it happens

Trigger: google.auth exceptions from bad service-account JSON, 403 Access Denied on the project/dataset, DNS/connectivity failures, or a custom query with syntax errors that surface at dry-run time.

Common situations: Expired or wrong-scoped service account; user lacks bigquery.jobs.create; malformed SQL in config['query']; egress-blocked environments.

Related errors

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