apache/seatunnel · error · BigQueryConnectorException

TABLE_NOT_FOUND

TABLE_NOT_FOUND

Error message

BigQuery target table does not exist: %s.%s.%s. Please create the target table before starting the sink.

What it means

Thrown by TableSchemaUtil.getActualTableSchema when bigquery.getTable() returns null, i.e. the configured project.dataset.table does not exist in BigQuery. The sink requires the target table to pre-exist because it reads its schema to build the write payload; it refuses to start rather than auto-creating a wrong-shaped table.

Source

Thrown at seatunnel-connectors-v2/connector-bigquery/src/main/java/org/apache/seatunnel/connectors/bigquery/sink/writer/TableSchemaUtil.java:98

                    .build();
        } catch (Descriptors.DescriptorValidationException | IOException e) {
            throw new BigQueryConnectorException(
                    BigQueryConnectorErrorCode.WRITER_CREATE_FAILED, e);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new BigQueryConnectorException(
                    BigQueryConnectorErrorCode.WRITER_CREATE_FAILED, e);
        }
    }

    static TableSchema getActualTableSchema(ReadonlyConfig config, boolean includeChangeTypeField) {
        String projectId = config.get(BigQuerySinkOptions.PROJECT_ID);
        String datasetId = config.get(BigQuerySinkOptions.DATASET_ID);
        String tableId = config.get(BigQuerySinkOptions.TABLE_ID);
        BigQuery bigquery = BigQueryClientFactory.getBigQuery(config);
        Table table = bigquery.getTable(TableId.of(projectId, datasetId, tableId));
        if (table == null) {
            throw new BigQueryConnectorException(
                    BigQueryConnectorErrorCode.TABLE_NOT_FOUND,
                    String.format(
                            "BigQuery target table does not exist: %s.%s.%s. "
                                    + "Please create the target table before starting the sink.",
                            projectId, datasetId, tableId));
        }
        Schema bqSchema = table.getDefinition().getSchema();
        TableSchema.Builder builder = TableSchema.newBuilder();

        if (bqSchema == null || bqSchema.getFields() == null) {
            throw CommonError.illegalArgument(
                    String.format(
                            "Table %s.%s.%s does not exist or has no schema.",
                            projectId, datasetId, tableId),
                    IDENTIFIER);
        }

        for (Field field : bqSchema.getFields()) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Create the target table first (CREATE TABLE in BigQuery or bq mk -t) matching your SeaTunnel schema, then rerun the job.
2. Verify the three config values with `bq show project:dataset.table` using the same credentials SeaTunnel uses.
3. Check the service account has BigQuery Table Viewer / Data Editor roles on the dataset.
4. Confirm dataset location matches the job's expected region and there is no project-id prefix mismatch (e.g. table placed in a different GCP project).

Example fix

// before (config)
PROJECT_ID = "my-proj"
DATASET_ID = "mydataset"
TABLE_ID = "mytable"
// after: create the table before running the sink
bq mk --table my-proj:mydataset.mytable schema.json

bq show --format=prettyjson ${PROJECT_ID}:${DATASET_ID}.${TABLE_ID} || echo 'table missing'

// catch TABLE_NOT_FOUND and surface a remediation message
try {
    runSink(cfg);
} catch (BigQueryConnectorException e) {
    if (BigQueryConnectorErrorCode.TABLE_NOT_FOUND.equals(e.getErrorCode())) {
        throw new IllegalStateException("Create table first: " + fqtn(cfg), e);
    } throw e;
}

When it happens

Trigger: getActualTableSchema calls BigQueryClientFactory.getBigQuery(config).getTable(TableId.of(projectId, datasetId, tableId)) and the API returns null because the table (or dataset/project) does not exist or is not visible to the credentials.

Common situations: Typo in PROJECT_ID/DATASET_ID/TABLE_ID in the sink config; table created in a different project; credentials lack bigquery.tables.get on the target; using a temp/dev table name that was never created; regional dataset accessed with wrong location settings.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• TABLE_CONFIG_NOT_FOUND
• Table {} is not found in catalog tables, skip to merge confi
• prepare method is not supported
• Option not be null.
• Condition operator must not be null

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