Codici di errore Spanner

Questa pagina descrive i codici di errore di Spanner e le azioni consigliate per gestirli. Le API di Google, inclusa Spanner, utilizzano i codici di errore canonici definiti da google.rpc.Code.

Quando una richiesta Spanner va a buon fine, l'API restituisce un codice di stato HTTP 200 OK insieme ai dati richiesti nel corpo della risposta.

Quando una richiesta non va a buon fine, l'API Spanner restituisce un codice di stato HTTP 4xx o 5xx che identifica genericamente l'errore, nonché una risposta che fornisce informazioni più specifiche sugli errori che hanno causato l'errore.

L'oggetto risposta contiene un singolo campo error il cui valore contiene i seguenti elementi:

Elemento Descrizione
code Un codice di stato HTTP che identifica in modo generico l'errore della richiesta.
message Informazioni specifiche sull'errore della richiesta.
status Il codice di errore canonico (google.rpc.Code) per le API di Google. I codici che possono essere restituiti dall'API Spanner sono elencati in Codici di errore.

Se una richiesta effettuata con un tipo di contenuto application/x-protobuf genera un errore, restituirà un messaggio google.rpc.Status serializzato come payload.

Codici di errore

Il modo consigliato per classificare gli errori è esaminare il valore del codice di errore canonico (google.rpc.Code). Negli errori JSON, questo codice viene visualizzato nel campo status. Negli errori application/x-protobuf, si trova nel campo code.

Codice di errore Descrizione Azione consigliata
ABORTED L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un errore di controllo del sequencer o un'interruzione della transazione. Indica che la richiesta è in conflitto con un'altra richiesta.

Per saperne di più sugli errori Database schema has changed, consulta Errore: lo schema del database è stato modificato.		 Per un commit non transazionale:
riprova a inviare la richiesta o struttura le entità in modo da ridurre la contesa.

Per le richieste che fanno parte di un commit transazionale:
riprova a inviare l'intera transazione o struttura le entità in modo da ridurre la contesa.
ALREADY_EXISTS L'entità che un client ha tentato di creare esiste già (ad esempio, l'inserimento di una riga con una chiave primaria esistente). Non riprovare senza risolvere il problema.
CANCELLED L'operazione è stata annullata, in genere dal chiamante. Riprova a eseguire l'operazione.
DEADLINE_EXCEEDED La scadenza è terminata prima che l'operazione potesse essere completata. Verifica se la scadenza è sufficiente. Utilizza una scadenza corrispondente al momento effettivo in cui una risposta è utile. Tieni presente che per le operazioni che modificano lo stato del sistema, potrebbe essere restituito un errore anche se l'operazione è stata completata correttamente.

Per suggerimenti, vedi Risolvere i problemi relativi agli errori di scadenza superata.
FAILED_PRECONDITION L'operazione è stata rifiutata perché non è stata soddisfatta una precondizione per la richiesta. Il campo del messaggio nella risposta di errore fornisce informazioni sulla precondizione non soddisfatta. Ad esempio, la lettura o l'esecuzione di query da un timestamp che ha superato la massima obsolescenza del timestamp. Non riprovare senza risolvere il problema.
INTERNAL Il server ha restituito un errore. Alcuni invarianti previsti dal sistema sottostante sono stati violati. Non riprovare a meno che tu non comprenda la circostanza e la causa specifiche dell'errore.
INVALID_ARGUMENT Il client ha specificato un valore non valido. Il campo del messaggio nella risposta di errore fornisce informazioni sul valore non valido. Non riprovare senza risolvere il problema.
NOT_FOUND Indica che alcune entità richieste, ad esempio l'aggiornamento di un'entità o l'interrogazione di una tabella o di una colonna, non esistono. Non riprovare senza risolvere il problema.
OUT_OF_RANGE L'operazione è stata tentata oltre l'intervallo valido. Non riprovare senza risolvere il problema.
PERMISSION_DENIED L'utente non era autorizzato a inviare la richiesta. Non riprovare senza risolvere il problema.
RESOURCE_EXHAUSTED Alcune risorse sono esaurite.

Per il piano amministratore, è possibile che il progetto abbia superato la quota o che l'intero file system sia esaurito.

Per il piano dati, questo può accadere se i nodi Spanner sono sovraccarichi.

Per ulteriori informazioni, consulta anche Codici di errore relativi alla sessione.		 Per il piano amministratore, verifica di non aver superato la quota di Spanner o del progetto. Se hai superato una quota, richiedi un aumento della quota o attendi il ripristino della quota prima di riprovare. Configura i nuovi tentativi in modo che utilizzino il backoff esponenziale.

Per il piano dati, verifica che i nodi Spanner non abbiano superato la capacità. Spanner riprova a seguito di questi errori nella libreria client. Se tutti i tentativi non vanno a buon fine, consulta Errori del meccanismo di controllo del flusso.

In generale, se la tua applicazione riscontra errori RESOURCE_EXHAUSTED, considera la situazione come un errore UNAVAILABLE e riprova con backoff esponenziale.
UNAUTHENTICATED La richiesta non ha credenziali di autenticazione valide per l'operazione. Non riprovare senza risolvere il problema.
UNAVAILABLE Il server non è disponibile. Riprova utilizzando il backoff esponenziale. Tieni presente che non è sempre sicuro riprovare le operazioni non idempotenti.
UNIMPLEMENTED L'operazione non è implementata o non è supportata/abilitata in questo servizio. Non riprovare senza risolvere il problema.
UNKNOWN Il server ha restituito un errore sconosciuto. Gli errori generati dalle API che non restituiscono informazioni sufficienti sugli errori potrebbero essere convertiti in questo errore. Verifica che la tua richiesta sia sicura. Dopodiché, riprova con il backoff esponenziale.

Errore: lo schema del database è cambiato

Potresti visualizzare un errore ABORTED con un messaggio simile a uno dei seguenti:

  • Database schema has changed
  • Transaction aborted. Database schema probably changed during transaction, retry may succeed.

Questi errori si verificano in genere quando un aggiornamento dello schema interrompe la transazione. Tuttavia, possono essere attivati anche per altri motivi senza un aggiornamento esplicito dello schema. Ad esempio, uno stato interno temporaneo, come uno schema client obsoleto durante il commit di una transazione, può attivare questo errore.

Come altri errori ABORTED, gestisci questo errore riprovando l'intera transazione.

Errori di sessione

Spanner utilizza le sessioni per gestire le interazioni tra l'applicazione e il database. Le sessioni rappresentano una connessione al database e facilitano operazioni come letture e scritture.

Gli errori comuni relativi alla sessione che la tua applicazione potrebbe riscontrare includono:

Sessione non trovata

L'errore Session not found si verifica quando l'applicazione tenta di utilizzare una sessione che non esiste più. Questo può accadere per diversi motivi.

  • L'applicazione client potrebbe eliminare esplicitamente una sessione. Ad esempio, la chiusura di un client di database nel codice o la chiamata diretta all'API deleteSessions rimuove la sessione. Se non utilizzi una delle librerie client di Spanner, crea una nuova sessione quando si verifica questo errore. Aggiungi la nuova sessione al pool di sessioni e rimuovi quella eliminata.

  • Spanner elimina automaticamente anche le sessioni in determinate condizioni.

    • Elimina una sessione se rimane inattiva per più di un'ora. Ciò può verificarsi nei job di stream di dati in cui l'elaborazione downstream richiede più tempo rispetto al timeout di inattività della sessione. Se utilizzi un job Dataflow, aggiungi un'operazione di trasformazione Reshuffle dopo la lettura di Spanner nella pipeline Dataflow. In questo modo è possibile disaccoppiare l'operazione di lettura di Spanner dai passaggi di elaborazione a lunga esecuzione successivi.

    • Spanner elimina anche una sessione se è più vecchia di 28 giorni. Se utilizzi la libreria client, questi casi vengono gestiti automaticamente. Se non utilizzi una delle librerie client di Spanner, crea una nuova sessione quando si verifica questo errore. Aggiungi la nuova sessione al pool di sessioni e rimuovi la sessione eliminata dal pool.

  • Se utilizzi una delle librerie client di Spanner, la libreria gestisce automaticamente le sessioni. Se si verifica questo errore, verifica che il codice non elimini esplicitamente le sessioni, ad esempio chiudendo il client di database. A volte, questo problema può essere causato anche da un problema nella gestione delle sessioni della libreria client.

Risorsa esaurita

Gli errori RESOURCE_EXHAUSTED: No session available in the pool o RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session indicano che la tua applicazione non può acquisire una sessione dal pool di sessioni. Ciò si verifica quando non sono disponibili sessioni per elaborare nuove richieste di lettura o scrittura.

La seguente tabella descrive alcuni motivi che potrebbero causare questi errori e le azioni consigliate corrispondenti.

Motivo Azione consigliata
Tutte le sessioni nel pool sono in uso. La tua applicazione potrebbe ricevere più richieste simultanee rispetto al numero massimo configurato di sessioni. Tutte le sessioni del pool sono occupate e non sono disponibili per nuove richieste. Attiva le sessioni multiplex. Le sessioni multiplexate consentono a più transazioni e letture di condividere una singola sessione, il che può ridurre il numero totale di sessioni richieste dalla tua applicazione. Puoi anche aumentare la configurazione di maxSession o minSession nelle impostazioni del pool di sessioni.
Le richieste richiedono molto tempo per essere completate. Le richieste di lettura o scrittura a esecuzione prolungata possono occupare tutte le sessioni disponibili per periodi prolungati. Se queste richieste richiedono più tempo dell'impostazione del timeout di acquisizione della sessione, le nuove richieste non possono ottenere una sessione dal pool di sessioni. Indaga sul motivo per cui le tue richieste richiedono molto tempo per essere completate. Ottimizza le query o la logica dell'applicazione per ridurre il tempo di esecuzione. Puoi aumentare l'impostazione del timeout di acquisizione della sessione. Puoi anche attivare le sessioni multiplexate per le librerie client idonee per migliorare l'utilizzo delle sessioni.
Sono presenti perdite di sessione. Una perdita di sessione si verifica quando la tua applicazione estrae una sessione dal pool, ma non la restituisce dopo aver completato la richiesta. Ciò si verifica in genere quando gli iteratori o i set di risultati non vengono chiusi correttamente nel codice. Se tutte le sessioni vengono compromesse, non sono disponibili sessioni per le nuove richieste. Esegui il debug del codice dell'applicazione per identificare e correggere le perdite di sessione. Assicurati che il codice chiuda correttamente tutti gli iteratori e i set di risultati. Per saperne di più, consulta Soluzioni di rilevamento della perdita di sessione. Puoi anche utilizzare la funzionalità di pulizia automatica delle perdite di sessione per impostare il pool di sessioni in modo che risolva automaticamente le transazioni inattive.
La creazione della sessione è lenta. La creazione di sessioni è un'operazione costosa in termini di calcolo. Le librerie client inviano API BatchCreateSessions per creare sessioni iniziali (in base alla configurazione minSession) e API CreateSessions per sessioni aggiuntive (fino a maxSession). Se la creazione della sessione richiede più tempo rispetto all'impostazione del timeout di acquisizione della sessione, le nuove richieste potrebbero andare in timeout durante l'attesa delle sessioni. Verifica la latenza delle chiamate API BatchCreateSessions e CreateSessions. La creazione lenta delle sessioni potrebbe derivare da problemi di risorse sul lato Spanner o da un gran numero di operazioni di creazione di sessioni simultanee.

Errori del meccanismo di controllo del flusso

Spanner potrebbe attivare il meccanismo di controllo del flusso per proteggersi dal sovraccarico nelle seguenti condizioni:

  • L'utilizzo della CPU sul nodo Spanner è elevato. Se sospetti che la tua richiesta stia causando un utilizzo elevato della CPU, puoi utilizzare le metriche di utilizzo della CPU per analizzare il problema.
  • Potrebbero esserci hotspot, che aumentano il tempo di elaborazione della richiesta. Se sospetti che la tua richiesta stia causando hotspot, consulta Trovare hotspot nel database per esaminare il problema. Per saperne di più, consulta Key Visualizer.

Il meccanismo di controllo del flusso è supportato dalle seguenti librerie client:

Il tempo complessivo per il completamento della richiesta non aumenterà a causa dell'utilizzo del meccanismo di controllo del flusso. Senza questo meccanismo, Spanner attende prima di elaborare la richiesta e alla fine restituisce un errore DEADLINE_EXCEEDED.

Quando il meccanismo di controllo del flusso è attivo, Spanner invia le richieste al client per riprovare. Se il nuovo tentativo consuma l'intero termine fornito dall'utente, il client riceve un errore RESOURCE_EXHAUSTED. Questo errore viene restituito se Spanner stima che il tempo di elaborazione della richiesta sia troppo lungo. L'errore propaga il controllo del flusso e Spanner riprova a inviare la richiesta al client, anziché accumulare i tentativi internamente. In questo modo, Spanner può evitare di accumulare un consumo di risorse aggiuntivo.