apache/iceberg · error · UncheckedIOException

Creating BigQuery client failed

Error message

Creating BigQuery client failed

What it means

BigQueryMetastoreCatalog.initialize() constructs the BigQuery metastore client from BigQueryOptions; an IOException during client creation is wrapped into this UncheckedIOException. It means the catalog could not establish the BigQuery client at all.

Source

Thrown at bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryMetastoreCatalog.java:90

  private CloseableGroup closeableGroup;

  public BigQueryMetastoreCatalog() {}

  @Override
  public void initialize(String name, Map<String, String> properties) {

    BigQueryProperties bigQueryProperties = new BigQueryProperties(properties);

    this.projectId = bigQueryProperties.projectId();
    this.projectLocation = bigQueryProperties.location();
    this.listAllTables = bigQueryProperties.listAllTables();

    BigQueryOptions bigQueryOptions = bigQueryProperties.metastoreOptions();

    try {
      client = new BigQueryMetastoreClientImpl(bigQueryOptions);
    } catch (IOException e) {
      throw new UncheckedIOException("Creating BigQuery client failed", e);
    } catch (GeneralSecurityException e) {
      throw new RuntimeException("Creating BigQuery client failed due to a security issue", e);
    }

    initialize(name, properties, projectId, projectLocation, client);
  }

  @VisibleForTesting
  void initialize(
      String name,
      Map<String, String> properties,
      String initialProjectId,
      String initialLocation,
      BigQueryMetastoreClient bigQueryMetaStoreClient) {
    Preconditions.checkArgument(bigQueryMetaStoreClient != null, "Invalid BigQuery client: null");
    this.catalogName = name;
    this.catalogProperties = ImmutableMap.copyOf(properties);
    this.projectId = initialProjectId;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the wrapped IOException cause for the root failure.
2. Verify BigQuery catalog properties (project id, endpoint, credentials path) are correct and the key file exists/readable.
3. Confirm network access to the BigQuery API endpoint from the runtime environment.
4. Validate that the service account credentials can be loaded (GOOGLE_APPLICATION_CREDENTIALS or configured key file).

// pre-check config
Preconditions.checkArgument(projectId != null && !projectId.isEmpty(), "project-id is required");
java.io.File keyFile = credentialsPath != null ? new java.io.File(credentialsPath) : null;
if (keyFile != null) Preconditions.checkArgument(keyFile.exists(), "credential file missing: " + credentialsPath);

try { catalog.initialize(name, props); } catch (UncheckedIOException e) { log.error("BigQuery client creation failed: {}", e.getCause()); throw e; }

When it happens

Trigger: new BigQueryMetastoreClientImpl(bigQueryOptions) throws IOException — bad project id, malformed options, credential file problems surfacing as IOException, or transport initialization failure.

Common situations: Wrong or missing project configuration in BigQueryProperties; invalid service account key file path; network egress blocked to bigquery.googleapis.com; malformed catalog properties generating bad BigQueryOptions.

Related errors

• Failed to create GCP cloud KMS service client
• Creating BigQuery client failed due to a security issue
• Table rename operation is unsupported.
• Namespace does not exist: %s
• %s

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/0fa317991b789ea5. Report an issue: GitHub.