Spanner 錯誤代碼

本頁面說明 Spanner 錯誤代碼,以及處理這些錯誤的建議做法。Google API (包括 Spanner) 使用 google.rpc.Code 定義的標準錯誤代碼。

Spanner 要求若成功,API 會在回應主體中傳回 HTTP 200 OK 狀態碼及所要求的資料。

若要求失敗,Spanner API 會傳回 HTTP 4xx5xx 狀態碼,此狀態碼通常能識別失敗,也能識別回應,此回應針對導致失敗的錯誤提供更多具體資訊。

回應物件包含單一欄位 error,此欄位的值含以下元素:

元素 說明
code HTTP 狀態碼,通常用於識別要求失敗情形。
message 要求失敗的相關具體資訊。
status Google API 的標準化錯誤代碼 (google.rpc.Code)。Spanner API 可能會傳回的代碼列於錯誤代碼一節中。

application/x-protobuf 內容類型提出的要求若發生錯誤,會傳回一則序列化的 google.rpc.Status 訊息做為酬載。

錯誤代碼

如要分類錯誤,建議檢查標準化錯誤代碼 (google.rpc.Code) 的值。在 JSON 錯誤中,此代碼會出現在 status 欄位。在 application/x-protobuf 錯誤中,則出現在 code 欄位。

錯誤代碼 說明 建議做法
ABORTED 作業已取消,原因通常是排序器檢查失敗或交易取消等並行問題。表示該項要求與另一項要求衝突。 非交易型修訂:
重試要求,或是調整實體結構以解決衝突。

若要求屬於交易型修訂:
重試整筆交易,或者以減少內容的方式調整實體架構。
ALREADY_EXISTS 用戶端嘗試建立的實體已存在 (例如插入具有現有主鍵的資料列)。 未修正問題前請勿重試。
CANCELLED 作業已取消,一般由呼叫者取消。 請重試作業。
DEADLINE_EXCEEDED 已超過期限,但作業尚未完成。 調查截止日期是否足夠。請根據回覆的實用性,設定適當的期限。請注意,針對會變更系統狀態的作業,即使作業順利完成也可能會傳回錯誤。

如需提示,請參閱「排解超過期限的錯誤」。
FAILED_PRECONDITION 作業遭拒,因為未達到該項要求的先決條件。錯誤回應中的訊息欄位說明未達到的先決條件。舉例來說,從超過最大時間戳記過時程度的時間戳記讀取或查詢資料。 未修正問題前請勿重試。
INTERNAL 伺服器傳回錯誤。基礎系統預期的特定不變值已損毀。 除非您瞭解錯誤的具體情況和原因,否則請勿重試。
INVALID_ARGUMENT 用戶端指定的無效值。錯誤回應中的訊息欄位說明無效值的相關資訊。 未修正問題前請勿重試。
NOT_FOUND 表示要求的實體不存在,例如更新實體或查詢資料表/資料欄。 未修正問題前請勿重試。
OUT_OF_RANGE 嘗試執行的作業超出有效範圍。 未修正問題前請勿重試。
PERMISSION_DENIED 使用者沒有提出要求的權限。 未修正問題前請勿重試。
RESOURCE_EXHAUSTED 已耗盡某些資源。

就管理員層面而言,可能是專案超出配額,也可能是整個檔案系統的空間不足。

就資料層面而言,如果 Spanner 節點負載過重,也可能發生這種情況。

詳情請參閱與工作階段相關的錯誤代碼
如果是管理員層級,請確認您未超過 Spanner 或專案配額。如果超出配額,請要求提高配額,或等待配額重設後再試。將重試次數設為使用指數輪詢。

如果是資料層,請確認 Spanner 節點未超出容量上限。Spanner 會在用戶端程式庫中重試這些錯誤。如果所有重試都失敗,請參閱「流量控制機制錯誤」。

一般來說,如果應用程式發生 RESOURCE_EXHAUSTED 錯誤,請將情況視為 UNAVAILABLE 錯誤,並透過指數輪詢重試。
UNAUTHENTICATED 要求中不含作業的有效驗證憑證。 未修正問題前請勿重試。
UNAVAILABLE 伺服器無法使用。 使用指數輪詢重試。請注意,重試非等冪作業並不一定安全。
UNIMPLEMENTED 未實作作業或作業在此服務中不受支援/未啟用。 未修正問題前請勿重試。
UNKNOWN 伺服器傳回不明錯誤。由 API 發出但未傳回充分錯誤資訊的錯誤,可能會轉換為此錯誤。 確認要求是否安全。然後以指數輪詢方式重試。

工作階段錯誤

Spanner 會使用工作階段管理應用程式與資料庫之間的互動。工作階段代表資料庫的連線,可協助執行讀取和寫入等作業。

應用程式可能會遇到的常見工作階段相關錯誤包括:

找不到工作階段

如果應用程式嘗試使用已不存在的會期,就會發生 Session not found 錯誤。可能原因如下:

  • 用戶端應用程式可能會明確刪除工作階段。舉例來說,在程式碼中關閉資料庫用戶端,或直接呼叫 deleteSessions API,都會移除工作階段。如果沒有使用任何 Spanner 用戶端程式庫,發生這項錯誤時請建立新的工作階段。將新工作階段新增至工作階段集區,並從集區中移除已刪除的工作階段。

  • 在特定情況下,Spanner 也會自動刪除工作階段。

    • 如果工作階段閒置超過一小時,系統就會刪除該工作階段。如果資料串流工作中的下游處理時間超過工作階段閒置逾時時間,就可能發生這種情況。如果您使用 Dataflow 工作,請在 Dataflow 管道中的 Spanner 讀取作業後,新增 Reshuffle 轉換作業。這有助於將 Spanner 讀取作業與後續的長時間執行處理步驟分離。

    • 如果工作階段超過 28 天,Spanner 也會刪除。如果您使用用戶端程式庫,系統會自動處理這些情況。如果未使用任何 Spanner 用戶端程式庫,請在發生這項錯誤時建立新工作階段。將新工作階段新增至工作階段集區,並從集區中移除已刪除的工作階段。

  • 如果您使用 Spanner 用戶端程式庫,程式庫會自動管理工作階段。如果遇到這個錯誤,請確認程式碼不會明確刪除工作階段,例如關閉資料庫用戶端。有時,這也可能是因為用戶端程式庫的會期管理發生問題。

資源已用盡

RESOURCE_EXHAUSTED: No session available in the poolRESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session 錯誤表示應用程式無法從工作階段集區取得工作階段。如果沒有可用的工作階段來處理新的讀取或寫入要求,就會發生這種情況。

下表說明可能導致這些錯誤的原因,以及建議採取的相應動作。

原因 建議做法
集區中的所有工作階段都在使用中。應用程式收到的並行要求數量,可能會超過設定的工作階段數量上限。集區中的所有工作階段都已占用,無法處理新的要求。 啟用多工處理工作階段。 多工工作階段可讓多筆交易和讀取作業共用單一工作階段,進而減少應用程式所需的工作階段總數。您也可以在工作階段集區設定中,增加 maxSessionminSession 設定。
要求處理時間過長。長時間執行的讀取或寫入要求可能會長時間占用所有可用工作階段。如果這些要求超過工作階段取得逾時設定,新要求就無法從工作階段集區取得工作階段。 調查要求為何需要很長時間才能完成。最佳化查詢或應用程式邏輯,縮短執行時間。您可以延長工作階段擷取逾時設定。您也可以為符合資格的用戶端程式庫啟用多工工作階段,提升工作階段使用率。
工作階段洩漏。如果應用程式從集區簽出工作階段,但完成要求後未傳回工作階段,就會發生工作階段洩漏。如果程式碼中的疊代器或結果集未正確關閉,通常就會發生這種情況。如果所有工作階段都洩漏,新要求就無法使用任何工作階段。 偵錯應用程式碼,找出並修正工作階段洩漏問題。 請確保程式碼會正確關閉所有疊代器和結果集。 詳情請參閱「工作階段洩漏偵測解決方案」。您也可以使用自動清除工作階段洩漏功能,將工作階段集區設為自動解決閒置交易。
工作階段建立速度緩慢。建立工作階段是運算成本高昂的作業。用戶端程式庫會傳送 BatchCreateSessions API,建立初始工作階段 (根據 minSession 設定),以及傳送 CreateSessions API,建立其他工作階段 (最多 maxSession)。如果建立工作階段的時間超過工作階段擷取逾時設定,新要求可能會在等待工作階段時逾時。 確認 BatchCreateSessionsCreateSessions API 呼叫的延遲時間。如果 Spanner 發生資源問題,或是同時建立大量工作階段,可能會導致工作階段建立作業緩慢。

流量控制機制錯誤

在下列情況下,Spanner 可能會啟動流量控制機制,避免自身過載:

  • Spanner 節點的 CPU 使用率偏高。如果您懷疑要求導致 CPU 使用率偏高,可以使用 CPU 使用率指標調查問題。
  • 可能會有熱點,導致要求處理時間增加。 如果懷疑要求造成熱點,請參閱「找出資料庫中的熱點」一文,調查問題。詳情請參閱「Key Visualizer」。

下列用戶端程式庫支援流量控制機制:

使用流量控制機制不會增加要求完成的整體時間。如果沒有這項機制,Spanner 會先等待,再處理要求,最後傳回 DEADLINE_EXCEEDED 錯誤。

當流量控制機制處於啟用狀態時,Spanner 會將要求推回用戶端,以供重試。如果重試作業耗盡使用者提供的整個期限,用戶端就會收到 RESOURCE_EXHAUSTED 錯誤。如果 Spanner 預估要求處理時間過長,就會傳回這個錯誤。錯誤會傳播流量控制,而 Spanner 會向用戶端重試要求,而不是在內部累積重試次數。這樣 Spanner 就不會累積額外的資源消耗量。