Error messages

This document describes error messages that you might encounter when working with BigQuery, including HTTP error codes and suggested troubleshooting steps.

For more information about query errors, see Troubleshoot query errors.

For more information about streaming insert errors, see Troubleshoot streaming inserts.

Error table

Responses from the BigQuery API include an HTTP error code and an error object in the response body. An error object is typically one of the following:

An errors object, which contains an array of ErrorProto objects.
An errorResults object, which contains a single ErrorProto object.

The Error message column in the following table maps to the reason property in an ErrorProto object.

The table does not include all possible HTTP errors or other networking errors. Therefore, don't assume that an error object is present in every error response from BigQuery. In addition, you might receive different errors or error objects if you use the Cloud Client Libraries for the BigQuery API. For more information, see BigQuery API Client Libraries.

If you receive an HTTP response code that doesn't appear in the following table, the response code indicates an issue or an expected result with the HTTP request. Response codes in the 5xx range indicate a server-side error. If you receive a 5xx response code, then retry the request later. In some cases, a 5xx response code might be returned by an intermediate server such as a proxy. Examine the response body and response headers for details about the error. For a full list of HTTP response codes, see HTTP response codes.

If you use the bq command-line tool to check job status, the error object is not returned by default. To view the error object and the corresponding reason property that maps to the following table, use the --format=prettyjson flag. For example, bq --format=prettyjson show -j *<job id>*. To view verbose logging for the bq tool, use --apilog=stdout. To learn more about troubleshooting the bq tool, see Debugging.

Error message	HTTP code	Description	Troubleshooting
accessDenied	403	This error returns when you try to access a resource such as a dataset, table, view, or job that you don't have access to. This error also returns when you try to modify a read-only object.	Contact the resource owner and request access to the resource for the user identified by the `principalEmail` value in the error's audit log.
attributeError	400	This error returns when there is an issue with the user code where a certain object attribute is called but does not exist.	Ensure that the object you are working with has the attribute you are trying to access. For more information on this error, see AttributeError.
backendError	500, 502, 503 or 504	This error indicates that the service is currently unavailable. This can happen due to a number of transient issues, including: Service demand surge: Sudden spikes in demand, such as peak usage times, can result in load shedding to protect the quality of service for all BigQuery users. To prevent the system from getting overwhelmed BigQuery can return 500 or 503 errors for a small portion of requests. Network issues: The distributed nature of BigQuery means data is often transferred between different components or machines in the system. Various intermittent network connectivity issues can cause BigQuery to return a 5xx error, including SSL handshake failures, or other network infrastructure issues between the user and Google Cloud. Resource exhaustion: BigQuery has various internal resource limits in place to protect the overall service performance from a single user or a single job from consuming too many resources. BigQuery implements load shedding to tackle resource exhaustion. Backend errors: In rare cases, an internal problem within one of the BigQuery components can result in a 500 or 503 error returned to the client.	5xx errors are service-side issues and the client has no way to fix or control them. From the client side, in order to mitigate the impact of 5xx errors, you need to retry your requests using truncated exponential backoffs. For more information about exponential backoffs, see Exponential backoff. However, there are two special cases for troubleshooting this error: `jobs.get` calls and `jobs.insert` calls. `jobs.get` calls If you received a 503 error when polling `jobs.get`, wait a few seconds and poll again. If the job completes but includes an error object that contains `backendError`, the job failed. You can safely retry the job without concerns about data consistency. `jobs.insert` calls If you receive this error when making a `jobs.insert` call, it's unclear if the job succeeded. In this situation, you'll need to retry the job. If the retries are not effective and the issues persist, you can calculate the rate of failing requests and contact support. Also, if you observe a specific request to BigQuery persistently fail with a 5xx error, even when retried using exponential backoff on multiple workflow restart attempts, you should escalate this to support to troubleshoot the issue from the BigQuery side, regardless of the overall calculated error rate. Make sure to clearly communicate the business impact so that the issue can be triaged correctly.
badRequest	400	The error `'UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported'` can occur when some recently streamed rows in a table might not be available for DML operations (`DELETE`, `UPDATE`,`MERGE`), typically for a few minutes, but in rare cases, up to 90 minutes. For more information, see Streaming data availability and DML Limitations.	Wait a few minutes and try again, or filter your statement to only operate on older data that is outside of the streaming buffer. To see if data is available for table DML operations, check the `tables.get` response for the streamingBuffer section. If the streamingBuffer section is absent, then table data is available for DML operations. You can also use the `streamingBuffer.oldestEntryTime` field to identify the age of records in the streaming buffer. Alternatively, consider streaming data with the BigQuery Storage Write API (gRPC), which doesn't have this limitation.
billingNotEnabled	403	This error returns when billing isn't enabled for the project.	Enable billing for the project in the Google Cloud console.
billingTierLimitExceeded	400	This error returns when the value of `statistics.query.billingTier` for an on-demand Job exceeds 100. This occurs when on-demand queries use too much CPU relative to the amount of data scanned. For instructions on how to inspect job details, see Managing jobs.	This error most often results from executing inefficient cross-joins, either explicitly or implicitly, for example due to an inexact join condition. These types of queries are not suitable for on-demand pricing due to high resource consumption, and in general they may not scale well. You can either optimize the query or switch to use the capacity-based (slots) pricing model to resolve this error. For information about optimizing queries, see Avoiding SQL anti-patterns.
blocked	403	This error returns when BigQuery has temporarily denylisted the operation you attempted to perform, usually to prevent a service outage.	Contact support for more information.
duplicate	409	This error returns when trying to create a job, dataset, or table that already exists. The error also returns when a job's `writeDisposition` property is set to `WRITE_EMPTY` and the destination table accessed by the job already exists.	Rename the resource you're trying to create, or change the `writeDisposition` value in the job. For more information, see how to troubleshoot the Job already exists error.
internalError	500	This error returns when an internal error occurs within BigQuery.	Wait according to the back-off requirements described in the BigQuery Service Level Agreement, then try the operation again. If the error continues to occur, contact support or file a bug using the BigQuery issue tracker. You can also reduce the frequency of this error by using Reservations.
invalid	400	This error returns when there is any type of invalid input other than an invalid query, such as missing required fields or an invalid table schema. Invalid queries return an `invalidQuery` error.
invalidQuery	400	This error returns when you attempt to run an invalid query.	Check your query for syntax errors. The query reference contains descriptions and examples of how to construct valid queries.
invalidUser	400	This error returns when you attempt to schedule a query with invalid user credentials.	Refresh the user credentials, as explained in Scheduling queries.
jobBackendError	400	This error returns when the job was created successfully, but failed with an internal error. You might see this error in `jobs.query` or `jobs.getQueryResults`.	Retry the job with a new `jobId`. If the error continues to occur, contact support.
jobInternalError	400	This error returns when the job was created successfully, but failed with an internal error. You might see this error in `jobs.query` or `jobs.getQueryResults`.	Retry the job with a new `jobId`. If the error continues to occur, contact support.
jobRateLimitExceeded	400