错误消息

本文档介绍使用 BigQuery 时可能会遇到的错误消息，包括 HTTP 错误代码和建议的问题排查步骤。

如需详细了解查询错误，请参阅排查查询错误。

如需详细了解流式插入错误，请参阅排查流式插入问题。

错误表

BigQuery API 的响应在响应正文中包含 HTTP 错误代码和错误对象。错误对象通常是以下各项之一：

下表中的错误消息列会映射到 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 工具进行问题排查，请参阅调试。

<trid="jobratelimitexceeded"> </trid="jobratelimitexceeded">
错误消息 HTTP 代码 说明 问题排查
accessDenied 403

当您尝试访问您无权访问的数据集、表、视图或作业等资源时，系统会返回此错误。当尝试修改只读对象时，也会返回此错误。

联系资源所有者，并为错误审核日志中的 principalEmail 值标识的用户请求获取该资源的访问权限。
attributeError 400

当用户代码存在问题（调用了某个对象属性，但该属性不存在）时，系统会返回此错误。

确保您正在处理的对象具有您尝试访问的属性。如需详细了解此错误，请参阅 AttributeError。
backendError 500、503 或 504

此错误表示相应服务当前不可用。这可能是由于多种暂时性问题引起的，包括：

  • 服务需求激增：需求突然激增（例如在使用高峰期）可能会导致减载，以保护所有 BigQuery 用户的服务质量。为防止系统过载，BigQuery 可能会针对一小部分请求返回 500 或 503 错误。
  • 网络问题：BigQuery 的分布式特性意味着数据通常会在系统中的不同组件或机器之间传输。各种间歇性网络连接问题可能会导致 BigQuery 返回 5xx 错误，包括 SSL 握手失败，或用户和Google Cloud之间的其他网络基础设施问题。
  • 资源耗尽：BigQuery 具有各种内部资源限制，以防止单个用户或单个作业消耗过多资源，从而保护整体服务性能。BigQuery 会实现减载以解决资源耗尽问题。
  • 后端错误：在极少数情况下，某个 BigQuery 组件内部出现问题可能会导致向客户端返回 500 或 503 错误。

5xx 错误是服务端问题，客户端无法修复或控制这些问题。从客户端来看，为了减轻 5xx 错误的影响，您需要使用截断指数退避算法重试请求。如需详细了解指数退避算法，请参阅指数退避算法。不过，排查此错误时有两种特殊情况：jobs.get 调用和 jobs.insert 调用。

jobs.get 调用

  • 如果您在轮询 jobs.get 时收到 503 错误，请等待几秒钟再重新轮询。
  • 如果作业完成，但出现包含 backendError 的错误对象，则表示作业失败。您可以安全地重试该作业，而不用担心数据一致性。

jobs.insert 调用
如果您在进行 jobs.insert 调用时收到此错误，则无法确定作业是否成功。在此情况下，您需要重试该作业。

如果重试无效且问题仍然存在，您可以计算失败请求的比率并与支持团队联系。
此外，如果您发现对 BigQuery 的特定请求持续失败并返回 5xx 错误，即使在多次重试工作流时使用指数退避算法，您也应该将此问题上报给支持团队，以便从 BigQuery 端排查问题，无论计算出的总体错误率如何。请务必明确传达业务影响，以便正确分类问题。
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 字段标识流式传输缓冲区中记录的存在时间。

或者，您也可以考虑使用 BigQuery Storage Write API 流式传输数据，该 API 没有此限制。
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 问题跟踪器报告错误。您还可以使用预留来降低此错误的频率。
无效 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 配额，请与支持团队联系。如需修改自定义配额，请通过配额页面提交申请。如果您在使用 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"
  }
}

计算失败请求的比率和正常运行时间

大多数 500 和 503 错误都可以通过使用指数退避算法进行重试来解决。如果 500 和 503 错误仍然存在，您可以计算失败请求的总体比率和相应的正常运行时间，以并将其与 BigQuery 服务等级协议 (SLA) 进行比较，以确定服务是否按预期运行。

如需计算过去 30 天内的总体请求失败率，请取过去 30 天内特定 API 调用或方法的失败请求数，然后除以过去 30 天内该 API 调用或方法的总请求数。将此值乘以 100，即可得出 30 天内失败请求的平均百分比。

例如，您可以查询 Cloud Logging 数据，以获取 jobs.insert 请求总数和失败的 jobs.insert 请求数，然后执行计算。您还可以从 API 信息中心或使用 Cloud Monitoring 中的 Metrics Explorer 获取错误率值。这些选项不会包含客户端与 BigQuery 之间遇到的网络或路由问题的数据，因此我们还建议您使用客户端日志记录和报告系统以更精确地计算失败率。

首先，用 100% 减去失败请求的总体率。如果此值大于或等于 BigQuery SLA 中所述的值，则正常运行时间也符合 BigQuery SLA。不过，如果此值低于 SLA 中所述的值，请手动计算正常运行时间。

为了计算正常运行时间，您需要知道视为服务停机的时间（以分钟为单位）。服务停机时间是指，根据 SLA 定义计算的错误率超过 10% 的一分钟时间段。如需计算正常运行时间，请取过去 30 天内的总分钟数，然后减去服务关闭的总分钟数。将剩余时间除以过去 30 天的总分钟数，然后将此值乘以 100，即可得出 30 天内的正常运行时间百分比。如需详细了解与 SLA 相关的定义和计算，请参阅 BigQuery 服务等级协议 (SLA)

如果您的每月正常运行时间百分比大于或等于 BigQuery SLA 中所述的值，则该错误很可能是由暂时性问题导致的，因此您可以继续使用指数退避算法重试。

如果正常运行时间低于 SLA 中显示的值，请与支持团队联系以获取帮助，并分享观察到的总体错误率和正常运行时间计算结果。

身份验证错误

如 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"

    将 PROJECT_ID 替换为包含相应资源的项目 ID。

  • 搜索用于身份验证的特定用户或服务账号：

    resource.type="bigquery_resource"
protoPayload.authenticationInfo.principalEmail="EMAIL"

    将 EMAIL 替换为用户或服务账号的邮箱。

  • 在“管理员活动”审核日志中搜索 Identity and Access Management 政策更改：

    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

    将 DATASET_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 补丁 Python 当您尝试使用 HTTP 请求更新表资源时，系统会返回此错误。确保 HTTP 标头中的 ETag 未过时。对于表或数据集级操作，请确保资源自上次实例化后未发生更改，并根据需要重新创建对象。
无法建立新连接：[Errno 110] 连接超时 客户端库 当从 BigQuery 流式传输或读取数据时，此请求已到达文件末尾 (EOF) 时，系统会返回此错误。实现重试机制并设置更大的超时值。
socks.ProxyConnectionError：连接到 HTTP 代理时出错 :8080: [Errno 110] 连接超时 客户端库 排查代理状态和设置。实现重试机制并设置更大的超时值。
从传输流收到意外 EOF 或 0 字节 客户端库 实现重试机制并设置更大的超时值。

Google Cloud 控制台错误消息

下表列出了您在使用Google Cloud 控制台时可能会看到的错误消息。

错误消息 说明 问题排查
服务器返回未知错误响应。 当 Google Cloud 控制台从服务器收到未知错误时，系统会显示此错误；例如，当您点击数据集或其他类型的链接时，页面无法显示。 请切换到浏览器的无痕模式或不公开模式，然后重复导致该错误的操作。如果无痕模式下没有出现错误，则错误可能是由浏览器扩展程序（例如广告拦截器）导致的。在非无痕模式下停用浏览器扩展程序，看看是否能解决问题。