錯誤訊息

本文說明使用 BigQuery 時可能會遇到的錯誤訊息，包括 HTTP 錯誤代碼和建議的疑難排解步驟。

如要進一步瞭解查詢錯誤，請參閱「排解查詢錯誤」。

如要進一步瞭解串流資料即時插入錯誤，請參閱「排解串流資料即時插入問題」。

錯誤表格

BigQuery API 的回應會在回應主體中包含 HTTP 錯誤代碼和錯誤物件。錯誤物件通常是下列其中一種：

下表中的「錯誤訊息」欄位會對應至 ErrorProto 物件中的 reason 屬性。

資料表不會納入所有可能的 HTTP 錯誤或其他網路錯誤。 因此，請勿假設 BigQuery 的每個錯誤回應中都有錯誤物件。此外，如果您使用 BigQuery API 的 Cloud 用戶端程式庫，可能會收到不同的錯誤或錯誤物件。詳情請參閱「BigQuery API 用戶端程式庫」。

如果收到的 HTTP 回應代碼未列於下表，表示 HTTP 要求發生問題或產生預期結果。5xx 範圍內的回應代碼表示伺服器端錯誤。如果收到 5xx 回應代碼，請稍後重試要求。在某些情況下，中繼伺服器 (例如 Proxy) 可能會傳回 5xx 回應代碼。檢查回應主體和回應標頭，瞭解錯誤的詳細資訊。如需完整的 HTTP 回應代碼清單，請參閱「HTTP 回應代碼」。

如果您使用 bq 指令列工具檢查工作狀態，系統預設不會傳回錯誤物件。如要查看錯誤物件和對應的 reason 屬性 (對應至下表)，請使用 --format=prettyjson 旗標。例如：bq --format=prettyjson show -j *<job id>*。如要查看 bq 工具的詳細記錄，請使用 --apilog=stdout。如要進一步瞭解如何排解 bq 工具問題，請參閱「偵錯」。

錯誤訊息 HTTP 代碼 說明 疑難排解
accessDenied 403

當您嘗試存取沒有存取權的資源 (例如資料集、表格、檢視區塊或作業) 時，系統會傳回這項錯誤。如果您嘗試修改唯讀物件，也會傳回這個錯誤。

請聯絡資源擁有者，並要求存取資源，以供錯誤稽核記錄中 principalEmail 值所識別的使用者存取。
attributeError 400

如果使用者程式碼有問題，呼叫了不存在的特定物件屬性，就會傳回這個錯誤。

請確認您要使用的物件具有您嘗試存取的屬性。如要進一步瞭解這項錯誤，請參閱「AttributeError」。
backendError 500、502、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)，通常會持續幾分鐘，但極少數情況下，最多可能達 90 分鐘，這時就會發生 'UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported' 錯誤。詳情請參閱「串流資料可用性」和「DML 限制」。

請稍候幾分鐘再試一次，或篩選報表，只對串流緩衝區外的舊資料執行作業。如要查看資料是否適用於資料表 DML 作業，請檢查 tables.get 回應的「streamingBuffer」部分。如果沒有 streamingBuffer 區段，則資料表資料可用於 DML 作業。您也可以使用 streamingBuffer.oldestEntryTime 欄位，找出串流緩衝區中記錄的年齡。

或者，您也可以考慮使用 BigQuery Storage Write API (gRPC) 串流資料，這個 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

當要求缺少 Proxy 伺服器的有效驗證憑證時，用戶端環境和 Proxy 伺服器之間會傳回這項錯誤。詳情請參閱「407 要求 Proxy 驗證」。

排解問題時，請考量您的環境。如果在 Java 中作業時收到這項錯誤，請確認您已設定 jdk.http.auth.tunneling.disabledSchemes= 和 jdk.http.auth.proxying.disabledSchemes= 屬性，且等號後方沒有值。
quotaExceeded 403

如果專案超出 BigQuery 配額或自訂配額，或是您尚未設定帳單，但已超出查詢的免費層級，系統就會傳回這個錯誤。

如要進一步瞭解超出配額的項目，請查看錯誤物件的 message 屬性。如要重設或提高 BigQuery 配額，請與支援團隊聯絡。如要修改自訂配額，請透過「配額」頁面提出要求。如果您在使用 BigQuery 沙箱時收到這項錯誤，可以從沙箱升級。
詳情請參閱「排解 BigQuery 配額錯誤」。
rateLimitExceeded 403、429

如果專案在短時間內發出過多要求，導致超出短期速率限制，系統就會傳回這個錯誤。舉例來說，請參閱「查詢作業的速率限制」和「API 要求速率限制」。

降低要求比率。
如果認為專案未超過上述任一限制，請聯絡支援團隊。
詳情請參閱「排解 BigQuery 配額錯誤」。
resourceInUse 400

如果您嘗試刪除含有資料表的資料集，或是嘗試刪除目前正在執行的工作，就會收到這項錯誤。

請先清空資料集，再嘗試刪除，或等待工作完成再刪除。
resourcesExceeded 400

如果作業使用的資源過多，系統就會傳回這個錯誤。

如果作業使用的資源過多，系統就會傳回這個錯誤。如需疑難排解資訊，請參閱「排解資源超出限制錯誤」。
responseTooLarge 403

如果查詢結果大於回應大小上限，系統就會傳回這項錯誤。部分查詢會分多個階段執行，即使最終結果小於上限，只要任何階段傳回的回應大小過大，就會傳回這項錯誤。如果查詢使用 ORDER BY 子句，通常會傳回這個錯誤。

有時，加入 LIMIT 子句或移除 ORDER BY 子句會有幫助。如要確保系統可以傳回大型結果，請將 allowLargeResults 屬性設為 true，並指定目的地資料表。詳情請參閱「寫入大型查詢結果」。
已停止 200

工作遭到取消時會傳回這個狀態碼。
tableUnavailable 400

某些 BigQuery 資料表是由其他 Google 產品團隊管理的資料所支援。這個錯誤表示其中一個資料表無法使用。

遇到這則錯誤訊息時，您可以重試要求 (請參閱 internalError 疑難排解建議)，或聯絡授予您資料存取權的 Google 產品團隊。
逾時 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 天內的要求失敗率，請將特定 API 呼叫或方法在過去 30 天內的要求失敗次數，除以該 API 呼叫或方法在過去 30 天內的要求總次數。將這個值乘以 100，即可得出 30 天內要求失敗的平均百分比。

舉例來說，您可以查詢 Cloud Logging 資料，取得要求總數 jobs.insert 和失敗要求數 jobs.insert，然後進行計算。您也可以從 API 資訊主頁取得錯誤率值，或使用 Cloud Monitoring 中的 Metrics Explorer 取得。這些選項不會納入用戶端與 BigQuery 之間發生的網路或路由問題相關資料，因此我們也建議使用用戶端記錄和回報系統，更精確地計算失敗率。

首先，請從 100% 減去整體要求失敗率。如果這個值大於或等於 BigQuery SLA 中所述的值，則正常運作時間也符合 BigQuery SLA。不過，如果這個值小於服務等級協議中描述的值，請手動計算正常運作時間。

如要計算正常運作時間，您必須知道被視為服務停機的時間 (以分鐘為單位)。服務停機是指錯誤率超過 10% 的一分鐘時段，計算方式依據服務水準協議的定義。如要計算正常運作時間，請從過去 30 天的總分鐘數中，扣除服務停機的總分鐘數。將剩餘時間除以過去 30 天的總分鐘數，然後將這個值乘以 100，即可得出 30 天的正常運作時間百分比。如要進一步瞭解與服務水準協議相關的定義和計算方式，請參閱 BigQuery 服務水準協議。

如果您的每月正常運作時間百分比大於或等於 BigQuery SLA 中所述的值，則錯誤很可能是由暫時性問題所致，因此您可以繼續使用指數輪詢重試。

如果正常運作時間低於服務水準協議中顯示的值，請與支援團隊聯絡尋求協助，並分享觀察到的整體錯誤率和正常運作時間計算結果。

驗證錯誤

OAuth 權杖產生系統擲回的錯誤會傳回下列 JSON 物件，如 OAuth2 規格所定義。

{"error" : "_description_string_"}

錯誤訊息會隨附 HTTP 400 Bad Request 錯誤或 HTTP 401 Unauthorized 錯誤。_description_string_ 是 OAuth2 規格定義的錯誤代碼之一。例如：

{"error":"invalid_client"}

查看錯誤

您可以使用記錄探索工具，查看特定工作、使用者或其他範圍的驗證錯誤。以下是記錄探索器篩選器範例，可用於查看驗證錯誤：

  • 在「政策遭拒」稽核記錄中，搜尋權限問題導致失敗的工作：

    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 替換為使用者或服務帳戶的電子郵件地址。

  • 在管理員活動稽核記錄中，搜尋身分與存取權管理政策變更：

    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：讀取逾時 Java 設定較大的逾時值。
Connection has been shutdown: javax.net.ssl.SSLException: java.net.SocketException: Connection reset at com.google.cloud.bigquery.spi.v2.HttpBigQueryRpc.translate(HttpBigQueryRpc.java:115) Java 導入重試機制，並設定較大的逾時值。
javax.net.ssl.SSLHandshakeException：遠端主機終止了交握 Java 導入重試機制，並設定較大的逾時值。
BrokenPipeError: [Errno 32] Broken pipe Python 實作重試機制。如要進一步瞭解這項錯誤，請參閱「BrokenPipeError」。
連線已中止。RemoteDisconnected('Remote end closed connection without response' Python 設定較大的逾時值。
SSLEOFError (發生違反通訊協定的 EOF) Python 系統會傳回這項錯誤，而不是 413 (ENTITY_TOO_LARGE) HTTP 錯誤。縮減要求大小。
TaskCanceledException：工作已取消 .NET 程式庫 在用戶端增加逾時值。
google.api_core.exceptions.PreconditionFailed: 412 PATCH Python 使用 HTTP 要求更新表格資源時，系統會傳回這項錯誤。請確認 HTTP 標頭中的 ETag 並未過時。如果是表格或資料集層級的作業，請確認資源自上次例項化後未變更，並視需要重新建立物件。
無法建立新連線：[Errno 110] Connection timed out 用戶端程式庫 從 BigQuery 串流或讀取資料時，如果這項要求已到達檔案結尾 (EOF)，系統就會傳回這個錯誤。實作重試機制，並設定較大的逾時值。
socks.ProxyConnectionError: Error connecting to HTTP proxy :8080: [Errno 110] Connection timed out 用戶端程式庫 排解 Proxy 狀態和設定問題。實作重試機制，並設定較大的逾時值。
從傳輸串流收到非預期的 EOF 或 0 個位元組 用戶端程式庫 實作重試機制，並設定較大的逾時值。

Google Cloud 控制台錯誤訊息

下表列出在Google Cloud 控制台中作業時可能看見的錯誤訊息。

錯誤訊息 說明 疑難排解
伺服器傳回不明錯誤回應。 如果 Google Cloud 控制台從伺服器收到不明錯誤，就會顯示這項錯誤。舉例來說，當您點選資料集或其他類型的連結，但系統無法顯示該頁面時，就會發生這種情況。 切換至瀏覽器的無痕或私密模式，然後重複導致錯誤的動作。如果無痕模式沒有錯誤，則錯誤可能是因為瀏覽器擴充功能 (例如廣告攔截器)。在非無痕模式下停用瀏覽器擴充功能，看看是否能解決問題。