错误消息
本文档介绍使用 BigQuery 时可能会遇到的错误消息，包括 HTTP 错误代码和建议的问题排查步骤。
如需详细了解查询错误，请参阅排查查询错误。
如需详细了解流式插入错误，请参阅排查流式插入问题。
错误表
BigQuery API 的响应在响应正文中包含 HTTP 错误代码和错误对象。错误对象通常是以下各项之一：
errors对象，包含一个ErrorProto对象数组。- 一个
errorResults对象，其中包含一个ErrorProto对象。
下表中的错误消息列会映射到 ErrorProto 对象中的 reason 属性。
下表并未包含所有可能的 HTTP 错误或其他网络错误。因此，请勿假设 BigQuery 的每个错误响应中都存在错误对象。此外，如果您使用适用于 BigQuery API 的 Cloud 客户端库，您可能会收到不同的错误或错误对象。如需了解详情，请参阅 BigQuery API 客户端库。
如果收到的 HTTP 响应代码未显示在下表中，则该响应代码表示该 HTTP 请求存在问题或结果符合预期。5xx 范围内的响应代码表示服务器端错误。如果您收到 5xx 响应代码，则请稍后重试请求。在某些情况下，中间服务器（如代理）可能会返回 5xx 响应代码。检查响应正文和响应标头以详细了解错误。如需查看 HTTP 响应代码的完整列表，请参阅 HTTP 响应代码。
如果使用 bq 命令行工具检查作业状态，则默认情况下不会返回错误对象。如需查看映射到下表的错误对象以及相应的 reason 属性，请使用 --format=prettyjson 标志。例如 bq --format=prettyjson show -j <job
id>。如需查看 bq 工具的详细日志记录，请使用 --apilog=stdout。如需详细了解如何对 bq 工具进行问题排查，请参阅调试。
| 错误消息 | HTTP 代码 | 说明 | 问题排查 |
|---|---|---|---|
| accessDenied | 403 | 当您尝试访问您无权访问的数据集、表、视图或作业等资源时，系统会返回此错误。当尝试修改只读对象时，也会返回此错误。 | 联系资源所有者，并为错误审核日志中的 principalEmail 值标识的用户请求获取该资源的访问权限。 |
| backendError | 500 或 503 | 当存在临时服务器故障（例如网络连接问题或服务器过载）时，系统会返回此错误。 | 通常，请等待几秒钟，然后重试。如果问题再次出现，请使用指数退避算法重试。不过，排查此错误时有两种特殊情况：jobs.get 调用和 jobs.insert 调用。
如果您在进行 |
| badRequest | 400 | 如果表中的某些最近流式插入的行可能不可用于 DML 操作（DELETE、UPDATE、MERGE），则可能会出现 'UPDATE or DELETE statement over table <project.dataset.table> would
affect rows in the streaming buffer, which is not supported' 错误几分钟，但在极少数情况下错误持续的时间长达 90 分钟。如需了解详情，请参阅流式传输数据的可用性和 DML 限制。 |
如需了解数据是否可用于表 DML 操作，请查看 streamBuffer 部分的 tables.get 响应。如果 streamingBuffer 部分不存在，则表数据可用于 DML 操作。您还可以使用 streamingBuffer.oldestEntryTime 字段标识流式传输缓冲区中记录的存在时间。 |
| billingNotEnabled | 403 | 当项目未启用结算时，会返回此错误。 | 请在 Google Cloud 控制台中为项目启用结算功能。 |
| billingTierLimitExceeded | 400 | 当按需作业的值 statistics.query.billingTier 超过 100 时，系统会返回此错误。当按需查询使用的 CPU 数量相对于扫描的数据量过多时，会发生这种情况。如需了解如何检查作业详细信息，请参阅管理作业。
|
此错误最常见的原因是显式或隐式执行低效的交叉联接（例如联接条件不精确）。这些类型的查询因资源消耗量较大而不适合按需价格模式，且通常扩缩能力不佳。您可以优化查询，也可以改用基于容量（槽）价格模式来解决此错误。如需了解如何优化查询，请参阅避免 SQL 反模式。 |
| 已屏蔽 | 403 | 当 BigQuery 暂时将您尝试执行的操作列入拒绝名单（通常是为了防止服务中断）时，会返回此错误。 | 如需了解详情，请与支持团队联系。 |
| duplicate | 409 | 当尝试创建的作业、数据集或表已存在时，系统会返回此错误。如果作业的 writeDisposition 属性设置为 WRITE_EMPTY，且作业访问的目标表已存在，也会返回此错误。 |
请重命名您尝试创建的资源，或更改作业的 writeDisposition 值。 |
| internalError | 500 | 当 BigQuery 发生内部错误时，系统会返回此错误。 | 根据 BigQuery 服务等级协议中的退避要求等待，然后重新尝试操作。如果错误仍然存在，请与支持团队联系，或使用 BigQuery 问题跟踪器报告错误。您还可以使用预留来降低此错误的频率。 |
| invalid | 400 |
当存在无效查询之外的任何种类无效输入（例如，缺少必填字段或表架构无效）时，系统会返回此错误。无效查询返回 invalidQuery 错误。 |
|
| invalidQuery | 400 | 当尝试运行无效查询时，会返回此错误。 | 检查查询是否存在语法错误。查询参考中包含有关如何构造有效查询的说明和示例。 |
| invalidUser | 400 | 当您尝试安排具有无效用户凭据的查询时，系统会返回此错误。 | 按照安排查询中的说明刷新用户凭据。 |
| jobBackendError | 400 | 当作业创建成功但因内部错误而失败时，系统会返回此错误。您可能会在 jobs.query 或 jobs.getQueryResults 中看到此错误。 |
使用新的 jobId 重试作业。如果错误仍然存在，请与支持团队联系。 |
| jobInternalError | 400 | 当作业创建成功但因内部错误而失败时，系统会返回此错误。您可能会在 jobs.query 或 jobs.getQueryResults 中看到此错误。 |
使用新的 jobId 重试作业。如果错误仍然存在，请与支持团队联系。 |
| jobRateLimitExceeded | 400 | 当作业创建成功但因 rateLimitExceeded 错误而失败时，系统会返回此错误。您可能会在 jobs.query 或 jobs.getQueryResults 中看到此错误。 |
使用指数退避算法降低请求速率，然后使用新的 jobId 重试作业。 |
| notFound | 404 | 当您引用的资源（数据集、表或作业）不存在或请求中的位置与资源的位置不匹配时（例如，运行作业的位置），系统会返回此错误。如果使用表修饰器引用最近执行过流式插入操作的表，但该表已被删除，也可能会发生此错误。 | 在查询已删除的表之前，请更正资源名称、正确指定位置或在流式插入后至少等待 6 个小时。 |
| notImplemented | 501 | 当尝试访问未实现的功能时，会返回此作业错误。 | 如需了解详情，请与支持团队联系。 |
| proxyAuthenticationRequired | 407 | 当请求缺少用于代理服务器的有效身份验证凭据时，系统会在客户端环境和代理服务器之间返回此错误。如需了解详情，请参阅 407 需要进行代理身份验证。 | 问题排查因环境而异。如果您在使用 Java 时收到此错误，请确保您已设置 jdk.http.auth.tunneling.disabledSchemes= 和 jdk.http.auth.proxying.disabledSchemes= 属性，并且等号后没有值。 |
| quotaExceeded | 403 | 如果您的项目超过 BigQuery 配额、自定义配额，或者如果您尚未设置结算功能并且已超过查询的免费层级，则系统会返回此错误。 | 请查看错误对象的 message 属性，详细了解超出了哪一项配额。要重置或提高 BigQuery 配额，请与支持团队联系。要修改自定义配额，请通过 Google Cloud 控制台页面提交申请。如果您在使用 BigQuery 沙盒时收到此错误，则可以从沙盒升级。如需了解详情，请参阅排查 BigQuery 配额错误。 |
| rateLimitExceeded | 403 | 如果您的项目在很短时间内发送的请求过多，导致超出短期速率限制，则系统会返回此错误。例如，请参阅查询作业的速率限制和 API 请求的速率限制。 |
请降低请求速率。
如果您确信项目未超过其中任何一项限制，请与支持团队联系。 如需了解详情，请参阅排查 BigQuery 配额错误。 |
| resourceInUse | 400 | 当尝试删除包含表的数据集或当前正在运行的作业时，会返回此错误。 | 在清空数据集后再尝试删除该数据集，或者等待作业完成后再删除该作业。 |
| resourcesExceeded | 400 | 作业使用太多资源时，会返回此错误。 | 作业使用太多资源时，会返回此错误。如需了解问题排查信息，请参阅排查资源超出限制的错误。 |
| responseTooLarge | 403 | 当查询结果大于最大响应大小时，会返回此错误。某些查询会分多个阶段执行。当任何阶段返回的响应大小过大时，系统便会返回此错误，即使最终结果未超过大小上限也是如此。如果查询使用 ORDER BY 子句，系统通常会返回此错误。 |
请添加 LIMIT 子句（有时会有所帮助），或移除 ORDER BY 子句。如要确保大型结果能够顺利返回，您可以将 allowLargeResults 属性设置为 true 并指定目标表。如需了解详情，请参阅
写入大型查询结果。 |
| 已停止 | 200 | 当取消作业时，会返回此状态代码。 | |
| tableUnavailable | 400 | 某些 BigQuery 表由其他 Google 产品团队管理的数据提供支持。此错误表示其中一个表不可用。 | 收到此错误消息时，您可以重试请求（请参阅 internalError 问题排查建议），或联系授予您数据访问权限的 Google 产品团队。 |
| timeout | 400 | 作业超时。 | 请考虑减少操作执行的工作量，以便能够在设定的限制内完成。请参阅配额和限制。 |
错误响应示例
GET https://bigquery.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"
}
}
身份验证错误
如 OAuth2 规范所定义，OAuth 令牌生成系统引发的错误会返回以下 JSON 对象。
{"error" : "description_string"}
此错误会伴随着 HTTP 400 Bad Request 错误或 HTTP 401 Unauthorized 错误。description_string 是由 OAuth2 规范定义的其中一个错误代码。例如：
{"error":"invalid_client"}
查看错误
您可以使用 Logs Explorer 查看特定作业、用户或其他范围的身份验证错误。下面列举了一些 Logs Explorer 过滤条件示例，您可以使用这些过滤条件查看身份验证错误。
- 在“政策拒绝”审核日志中搜索存在权限问题的失败作业：
resource.type="bigquery_resource" protoPayload.status.message=~"Access Denied" logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"
- 搜索用于身份验证的特定用户或服务账号：
resource.type="bigquery_resource" protoPayload.authenticationInfo.principalEmail="EMAIL"
将
EMAIL替换为用户或服务账号的电子邮件地址。- 在“管理员活动”审核日志中搜索 IAM 政策更改：
protoPayload.methodName=~"SetIamPolicy" logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
- 在“数据访问”审核日志中搜索对特定 BigQuery 数据集所做的更改：
resource.type="bigquery_resource" protoPayload.resourceName="projects/PROJECT_ID/datasets/DATASET_ID" logName=projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access
替换以下内容：
PROJECT_ID：资源所在项目的 IDDATASET_ID：资源所在数据集的 ID
连接错误消息
下表列出了在使用客户端库或从代码调用 BigQuery API 时，由于间歇性连接问题而可能会看到的错误消息：
| 错误消息 | 客户端库或 API | 问题排查 |
|---|---|---|
| com.google.cloud.bigquery.BigQueryException: Read timed out（com.google.cloud.bigquery.BigQueryException：读取超时） | Java | 设置更大的超时值。 |
| 连接已关闭：javax.net.ssl.SSLException：java.net.SocketException：连接已在 com.google.cloud.bigquery.spi.v2.HttpBigQueryRpc.translate(HttpBigQueryRpc.java:115) 重置 | Java | 实现重试机制并设置更大的超时值。 |
| javax.net.ssl.SSLHandshakeException：远程主机终止了握手 | Java | 实现重试机制并设置更大的超时值。 |
| BrokenPipeError: [Errno 32] Broken pipe（BrokenPipeError：[Errno 32] 管道损坏） | Python | 实现重试机制。如需详细了解此错误，请参阅 BrokenPipeError。 |
| 连接已取消。RemoteDisconnected('远端关闭连接且无响应' | Python | 设置更大的超时值。 |
| SSLEOFError (EOF occurred in violation of protocol)（SSLEOFError [违反协议时发生了 EOF]） | Python | 系统会返回此错误，而不是 413 (ENTITY_TOO_LARGE) HTTP 错误。缩减请求的大小。 |
| TaskCanceledException：任务已取消 | .NET 库 | 增加客户端的超时值。 |
| google.api_core.exceptions.PreconditionFailed: 412 PATCH（google.api_core.exceptions.PreconditionFailed：412 补丁） | Python | 当您尝试使用 HTTP 请求更新表资源时，系统会返回此错误。确保 HTTP 标头中的 ETag 未过时。对于表或数据集级操作，请确保资源自上次实例化后未发生更改，并根据需要重新创建对象。 |
Google Cloud 控制台错误消息
下表列出了使用 Google Cloud 控制台时可能会看到的错误消息。
| 错误消息 | 说明 | 问题排查 |
|---|---|---|
| 服务器返回未知错误响应。 | 当 Google Cloud 控制台从服务器收到未知错误时，会显示此错误；例如，当您点击数据集或其他类型的链接时，页面无法显示。 | 请切换到浏览器的无痕模式或不公开模式，然后重复导致该错误的操作。如果无痕模式下没有出现错误，则错误可能是由浏览器扩展程序（例如广告拦截器）导致的。在非无痕模式下停用浏览器扩展程序，看看是否能解决问题。 |