googleapis/mcp-toolbox · error

unable to execute query: %w

Error message

unable to execute query: %w

What it means

The BigQuery query job could not be started. query.Run(ctx) submits the SQL to BigQuery and creates a job; any API-level rejection (invalid SQL, permission denied, quota, invalid parameters, bytes-billed limits) surfaces here wrapped with this message.

Source

Thrown at internal/sources/bigquery/bigquery.go:628

	if params != nil {
		query.Parameters = params
	}
	if connProps != nil {
		query.ConnectionProperties = connProps
	}
	if labels != nil {
		query.Labels = labels
	}
	if s.MaximumBytesBilled > 0 {
		query.MaxBytesBilled = s.MaximumBytesBilled
	}

	// This block handles SELECT statements, which return a row set.
	// We iterate through the results, convert each row into a map of
	// column names to values, and return the collection of rows.
	job, err := query.Run(ctx)
	if err != nil {
		return nil, fmt.Errorf("unable to execute query: %w", err)
	}
	it, err := job.Read(ctx)
	if err != nil {
		return nil, fmt.Errorf("unable to read query results: %w", err)
	}

	out := []any{}
	for s.MaxQueryResultRows <= 0 || len(out) < s.MaxQueryResultRows {
		var val []bigqueryapi.Value
		err = it.Next(&val)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return nil, fmt.Errorf("unable to iterate through query results: %w", err)
		}
		schema := it.Schema
		row := orderedmap.Row{}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped Google API error for the exact reason (invalidQuery, accessDenied, billingTierLimitExceeded, etc.) and fix the SQL or permissions accordingly
2. Grant the caller account roles/bigquery.jobUser (and dataViewer as needed) on the project/dataset
3. Check the query's estimated bytes against s.MaximumBytesBilled and raise the limit or optimize the query
4. Ensure query.Location matches the dataset's location

Example fix

// before
query.MaxBytesBilled = 10 * 1024 * 1024 // too low for scan
// after
query.MaxBytesBilled = 0 // unlimited, or a limit above estimated scanned bytes

// dry-run to validate before executing
q := client.Query(statement)
q.Parameters = params
q.Location = client.Location
q.DryRun = true
if _, err := q.Run(ctx); err != nil {
    return fmt.Errorf("query would fail: %w", err)
}

_, err := src.RunSQL(ctx, client, stmt, "SELECT", params, nil, nil)
if err != nil && strings.Contains(err.Error(), "unable to execute query") {
    var apiErr *googleapi.Error
    if errors.As(err, &apiErr) && (apiErr.Code == 429 || apiErr.Code >= 500) {
        return retryWithBackoff(ctx)
    }
    return err // non-retryable: fix SQL/permissions
}

When it happens

Trigger: Calling RunSQL via execute-sql style tools when BigQuery rejects the job creation: syntax errors in the statement, caller lacking bigquery.jobs.create, exceeding MaximumBytesBilled limits, rate/quota limits, unknown table/column in a dry-run-validating API, or invalid query parameters.

Common situations: Typos or dialect issues in SQL (legacy vs standard SQL), service account missing BigQuery Job User role, billing not enabled on the project, MaxBytesBilled set below the query's scanned bytes, or location mismatch between client and dataset.

Related errors

• allowedDataset '%s' not found in project '%s'
• failed to verify allowedDataset '%s' in project '%s': %w
• error executing sql: %w
• request failed with status %s: %s
• API returned non-200 status: %d %s

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/04230f852ccb5a6c. Report an issue: GitHub.