apache/seatunnel · error · CatalogException

Failed to open BigQueryCatalog

Error message

Failed to open BigQueryCatalog

What it means

BigQueryCatalog.open() initializes the BigQuery client via BigQueryClientFactory.getBigQuery(config). Any exception during client construction (credentials, project, transport) is wrapped into a CatalogException with a generic message; the real cause is in the attached exception.

Source

Thrown at seatunnel-connectors-v2/connector-bigquery/src/main/java/org/apache/seatunnel/connectors/bigquery/catalog/BigQueryCatalog.java:101

     * @param config the readonly configuration options containing BigQuery connection info
     */
    public BigQueryCatalog(String catalogName, ReadonlyConfig config) {
        this.catalogName = catalogName;
        this.config = config;
    }

    /**
     * Opens the catalog and initializes the BigQuery client.
     *
     * @throws CatalogException if the BigQuery client fails to initialize
     */
    @Override
    public void open() throws CatalogException {
        try {
            this.bigquery = BigQueryClientFactory.getBigQuery(config);
            log.info("BigQueryCatalog '{}' opened successfully.", catalogName);
        } catch (Exception e) {
            throw new CatalogException("Failed to open BigQueryCatalog", e);
        }
    }

    /**
     * Closes the catalog.
     *
     * @throws CatalogException if any resources fail to close
     */
    @Override
    public void close() throws CatalogException {
        // BigQuery service client doesn't hold open TCP sockets directly; it's a stateless HTTP
        // wrapper.
        log.info("BigQueryCatalog '{}' closed successfully.", catalogName);
    }

    /**
     * Returns the catalog name.
     *

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the cause of the CatalogException for the concrete failure (credentials, quota, DNS)
2. Set `GOOGLE_APPLICATION_CREDENTIALS` to a valid service-account JSON and ensure it exists on all worker nodes
3. Enable the BigQuery API on the project and grant the service account BigQuery roles (e.g. Data Viewer/Editor)
4. Confirm the project id in the config matches the GCP project and that googleapis.com is reachable

Example fix

// before (no credentials configured, client init fails)
catalog {
  factory = "BigQuery"
  project = "my-gcp-project"
}
// after
catalog {
  factory = "BigQuery"
  project = "my-gcp-project"
}
// plus on the environment:
// export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

// pre-check credentials and project before opening the catalog
String creds = System.getenv("GOOGLE_APPLICATION_CREDENTIALS");
if (creds == null || !new java.io.File(creds).exists()) {
    throw new IllegalStateException("GOOGLE_APPLICATION_CREDENTIALS not set or file missing");
}
// also verify BigQuery API enabled: gcloud services list --enabled | grep bigquery

try {
    catalog.open();
} catch (CatalogException e) {
    log.error("BigQuery catalog open failed; root cause:", e.getCause());
    // distinguish auth failure vs network vs project misconfiguration
}

When it happens

Trigger: Calling catalog.open() when Google Cloud credentials are missing/invalid, the service account lacks BigQuery permissions, the project id is wrong, or the BigQuery client factory cannot build the transport client.

Common situations: GOOGLE_APPLICATION_CREDENTIALS not set on worker nodes; service-account JSON path wrong or key revoked; no BigQuery API enabled on the project; network/proxy blocking googleapis.com; missing scopes on the credentials.

Related errors

• CLIENT_CREATE_FAILED
• Failed to list BigQuery databases (datasets)
• Failed to list tables in dataset:
• Failed to create BigQuery table:
• Failed to drop BigQuery table:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/4ab7954b75a56335. Report an issue: GitHub.