apache/iceberg · error · RuntimeIOException

%s

Error message

%s

What it means

RuntimeIOException from BigQueryMetastoreClientImpl.internalCreate when the tables.insert HTTP call to BigQuery fails with an IOException (network error, interrupted connection, transport failure). The message is the exception's own text, with the original exception chained as the cause.

Source

Thrown at bigquery/src/main/java/org/apache/iceberg/gcp/bigquery/BigQueryMetastoreClientImpl.java:361

      handleBigQueryRetryException(e);
    }

    return response;
  }

  private Table internalCreate(Table table) {
    try {
      HttpResponse response =
          client
              .tables()
              .insert(
                  Preconditions.checkNotNull(table.getTableReference()).getProjectId(),
                  Preconditions.checkNotNull(table.getTableReference()).getDatasetId(),
                  table)
              .executeUnparsed();
      return convertExceptionIfUnsuccessful(response).parseAs(Table.class);
    } catch (IOException e) {
      throw new RuntimeIOException("%s", e);
    } catch (AlreadyExistsException e) {
      throw new AlreadyExistsException(e, "Table already exists: %s", table);
    }
  }

  @Override
  public Table load(TableReference tableReference) {
    try {
      HttpResponse response =
          client
              .tables()
              .get(
                  tableReference.getProjectId(),
                  tableReference.getDatasetId(),
                  tableReference.getTableId())
              .executeUnparsed();
      if (response.getStatusCode() == HttpStatusCodes.STATUS_CODE_NOT_FOUND) {
        throw new NoSuchTableException("%s", response.getStatusMessage());

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry with backoff; RuntimeIOException here is usually transient
2. Verify network path to bigquery.googleapis.com (firewall, proxy, DNS)
3. Increase HTTP transport timeout configuration for the BigQuery client
4. Inspect the chained cause (e.getCause()) for the root transport error

Example fix

// before
catalog.createTable(ident, schema); // transient IOException aborts job
// after
try {
  catalog.createTable(ident, schema);
} catch (RuntimeIOException e) {
  // retry with backoff
}

try { client.create(table); } catch (RuntimeIOException e) { /* retry with exponential backoff; inspect e.getCause() */ }

When it happens

Trigger: client.create(table) (via catalog.buildTable/registerTable create paths) where the underlying HTTP transport to the BigQuery API breaks: DNS failure, socket timeout, connection reset, or interrupted request.

Common situations: Transient GCP API outages, VPC/egress firewall blocking googleapis.com, proxy misconfiguration, long request bodies dropped on flaky networks, tight HTTP timeouts under load.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to read from input stream
• Creating BigQuery client failed
• Failed to read stream while finding starting row position
• Failed to check range end: %d
• Failed to get RRSA credentials

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