Troubleshooting Errors

You'll encounter two types of errors when working with BigQuery: HTTP error codes or job errors. Job errors are represented in the status object when calling jobs.get().

Error table

The following table lists possible error codes that return when making a request to the BigQuery API. API responses include an HTTP error code and an errors object. The "Error code" column below maps to the reason property in the error object.

If you use the bq command-line tool to check job status, the error object is not returned by default. To view the object and the corresponding reason property that maps to the below table, use the --format=prettyjson flag. For example, bq --format=prettyjson show -j <job id>

If you receive an HTTP response code that doesn't appear in the list below, the response code indicates an issue or an expected result with the HTTP request. For example, a 502 error indicates there is an issue with your network connection. For a full list of HTTP response codes, see HTTP response codes.

Sample error response

GET https://www.googleapis.com/bigquery/v2/projects/12345/datasets/foo
Response:
[404]
{
  "error": {
  "errors": [
  {
    "domain": "global",
    "reason": "notFound",
    "message": "Not Found: Dataset myproject:foo"
  }],
  "code": 404,
  "message": "Not Found: Dataset myproject:foo"
  }
}

Authentication errors

Errors thrown by the OAuth token generation system return the following JSON object, as defined by the OAuth2 specification.

{"error" : "description_string"}

The error is accompanied by either an HTTP 400 Bad Request error or an HTTP 401 Unauthorized error. description_string is one of the error codes defined by the OAuth2 specification. For example:

{"error":"invalid_client"}

Back to top

Troubleshooting streaming inserts

The following sections discuss how to troubleshoot errors that occur when you stream data into BigQuery.

Failure HTTP response codes

If you receive a failure HTTP response code such as a network error, there's no way to tell if the streaming insert succeeded. If you try to simply re-send the request, you might end up with duplicated rows in your table. To help protect your table against duplication, set the insertId property when sending your request. BigQuery uses the insertId property for de-duplication.

If you receive a permission error, an invalid table name error or an exceeded quota error, no rows are inserted and the entire request fails.

Success HTTP response codes

Even if you receive a success HTTP response code, you'll need to check the insertErrors property of the response to determine if the row insertions were successful, because it's possible that BigQuery was only partially successful at inserting the rows.

If the insertErrors property is an empty list, all of the rows inserted successfully. Otherwise, except in cases where there was a schema mismatch in any of the rows, rows indicated in the insertErrors property were not inserted, and all other rows were inserted successfully. The errors property contains detailed information about why each unsuccessful row failed. The index property indicates the 0-based row index of the request that the error applies to.

If BigQuery encounters a schema mismatch on individual rows in the request, none of the rows are inserted and an insertErrors entry is returned for each row, even the rows that did not have a schema mismatch. Rows that did not have a schema mismatch will have an error with the reason property set to stopped, and can be re-sent as-is. Rows that failed include detailed information about the schema mismatch.

Back to top