Messaggi di errore

Questo documento descrive i messaggi di errore che potresti riscontrare quando utilizzi BigQuery, inclusi i codici di errore HTTP e i passaggi consigliati per la risoluzione dei problemi.

Per saperne di più sugli errori delle query, vedi Risolvere gli errori delle query.

Per saperne di più sugli errori di inserimento di flussi di dati, consulta la pagina Risolvere i problemi relativi agli inserimenti di flussi di dati.

Tabella degli errori

Le risposte dell'API BigQuery includono un codice di errore HTTP e un oggetto di errore nel corpo della risposta. Un oggetto errore è in genere uno dei seguenti:

La colonna Messaggio di errore nella tabella seguente corrisponde alla proprietà reason in un oggetto ErrorProto.

La tabella non include tutti i possibili errori HTTP o altri errori di rete. Pertanto, non dare per scontato che un oggetto di errore sia presente in ogni risposta di errore di BigQuery. Inoltre, potresti ricevere errori o oggetti di errore diversi se utilizzi le librerie client di Google Cloud per l'API BigQuery. Per maggiori informazioni, consulta Librerie client dell'API BigQuery.

Se ricevi un codice di risposta HTTP che non è presente nella tabella seguente, il codice di risposta indica un problema o un risultato previsto con la richiesta HTTP. I codici di risposta nell'intervallo 5xx indicano un errore lato server. Se ricevi un codice di risposta 5xx, riprova a inviare la richiesta in un secondo momento. In alcuni casi, un codice di risposta 5xx potrebbe essere restituito da un server intermedio come un proxy. Esamina il corpo della risposta e le intestazioni della risposta per i dettagli sull'errore. Per un elenco completo dei codici di risposta HTTP, consulta Codici di risposta HTTP.

Se utilizzi lo strumento a riga di comando bq per controllare lo stato del job, l'oggetto errore non viene restituito per impostazione predefinita. Per visualizzare l'oggetto errore e la proprietà reason corrispondente che corrisponde alla tabella seguente, utilizza il flag --format=prettyjson. Ad esempio: bq --format=prettyjson show -j *<job id>*. Per visualizzare la registrazione dettagliata dello strumento bq, utilizza --apilog=stdout. Per saperne di più sulla risoluzione dei problemi relativi allo strumento bq, consulta la sezione Debug.

Messaggio di errore Codice HTTP Descrizione Risoluzione dei problemi
accessDenied 403

Questo errore viene restituito quando tenti di accedere a una risorsa come un set di dati, una tabella, una visualizzazione o un job a cui non hai accesso. Questo errore viene restituito anche quando tenti di modificare un oggetto di sola lettura.

Contatta il proprietario della risorsa e richiedi l'accesso alla risorsa per l'utente identificato dal valore principalEmail nel log di controllo dell'errore.
attributeError 400

Questo errore viene restituito quando si verifica un problema con il codice utente in cui viene chiamato un determinato attributo dell'oggetto, ma non esiste.

Assicurati che l'oggetto con cui stai lavorando abbia l'attributo a cui stai tentando di accedere. Per saperne di più su questo errore, consulta AttributeError.
backendError 500, 503 o 504

Questo errore indica che il servizio non è al momento disponibile. Ciò può accadere a causa di una serie di problemi temporanei, tra cui:

  • Aumento improvviso della domanda di servizi: picchi improvvisi della domanda, ad esempio durante gli orari di picco di utilizzo, possono comportare la riduzione del carico per proteggere la qualità del servizio per tutti gli utenti BigQuery. Per evitare che il sistema venga sovraccaricato, BigQuery può restituire errori 500 o 503 per una piccola parte delle richieste.
  • Problemi di rete: la natura distribuita di BigQuery implica che i dati vengono spesso trasferiti tra diversi componenti o macchine del sistema. Diversi problemi di connettività di rete intermittente possono causare la restituzione di un errore 5xx da parte di BigQuery, inclusi errori di handshake SSL o altri problemi di infrastruttura di rete tra l'utente e Google Cloud.
  • Esaurimento delle risorse: BigQuery ha vari limiti interni delle risorse per proteggere le prestazioni complessive del servizio dal consumo eccessivo di risorse da parte di un singolo utente o di un singolo job. BigQuery implementa il load shedding per risolvere il problema dell'esaurimento delle risorse.
  • Errori di backend: in rari casi, un problema interno a uno dei componenti di BigQuery può comportare la restituzione di un errore 500 o 503 al client.

Gli errori 5xx sono problemi lato servizio e il client non ha modo di risolverli o controllarli. Dal lato client, per mitigare l'impatto degli errori 5xx, devi riprovare a inviare le richieste utilizzando backoff esponenziali troncati. Per saperne di più sui backoff esponenziali, consulta Backoff esponenziale. Tuttavia, esistono due casi speciali per la risoluzione dei problemi relativi a questo errore: le chiamate jobs.get e le chiamate jobs.insert.

Chiamate jobs.get

  • Se hai ricevuto un errore 503 durante il polling jobs.get, attendi qualche secondo e riprova.
  • Se il job viene completato, ma include un oggetto di errore che contiene backendError, il job non è riuscito. Puoi riprovare in sicurezza il job senza preoccuparti della coerenza dei dati.

Chiamate jobs.insert
Se ricevi questo errore quando effettui una chiamata jobs.insert, non è chiaro se il job è stato eseguito correttamente. In questa situazione, dovrai riprovare il job.

Se i tentativi non sono efficaci e i problemi persistono, puoi calcolare la percentuale di richieste non riuscite e contattare l'assistenza.
Inoltre, se noti che una richiesta specifica a BigQuery non va a buon fine in modo persistente con un errore 5xx, anche se riprovata utilizzando il backoff esponenziale in più tentativi di riavvio del flusso di lavoro, devi riassegnare il problema all'assistenza per risolvere il problema dal lato BigQuery, indipendentemente dal tasso di errore complessivo calcolato. Assicurati di comunicare chiaramente l'impatto sull'attività in modo che il problema possa essere valutato correttamente.
badRequest 400

L'errore 'UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported' può verificarsi quando alcune righe trasmesse in streaming di recente in una tabella potrebbero non essere disponibili per le operazioni DML (DELETE, UPDATE,MERGE), in genere per alcuni minuti, ma in rari casi, fino a 90 minuti. Per ulteriori informazioni, vedi Disponibilità dei dati di streaming e Limitazioni DML.

Attendi qualche minuto e riprova oppure filtra l'istruzione in modo da operare solo sui dati meno recenti che si trovano al di fuori del buffer di streaming. Per verificare se i dati sono disponibili per le operazioni DML della tabella, controlla la tables.get risposta per la sezione streamingBuffer. Se la sezione streamingBuffer non è presente, i dati della tabella sono disponibili per le operazioni DML. Puoi anche utilizzare il campo streamingBuffer.oldestEntryTime per identificare l'età dei record nel buffer di streaming.

In alternativa, valuta la possibilità di trasmettere dati in streaming con l'API BigQuery Storage Write, che non presenta questa limitazione.
billingNotEnabled 403

Questo errore viene restituito quando la fatturazione non è abilitata per il progetto.

Abilita la fatturazione per il progetto nella consoleGoogle Cloud .
billingTierLimitExceeded 400

Questo errore viene restituito quando il valore di statistics.query.billingTier per un job on demand supera 100. Ciò si verifica quando le query on demand utilizzano troppa CPU rispetto alla quantità di dati analizzati. Per istruzioni su come esaminare i dettagli dei job, vedi Gestione dei job.

Questo errore si verifica più spesso a causa dell'esecuzione di cross-join inefficienti, in modo esplicito o implicito, ad esempio a causa di una condizione di join inesatta. Questi tipi di query non sono adatti ai prezzi on demand a causa dell'elevato consumo di risorse e, in generale, potrebbero non essere scalabili. Per risolvere questo errore, puoi ottimizzare la query o passare all'utilizzo del modello di prezzi basato sulla capacità (slot). Per informazioni sull'ottimizzazione delle query, vedi Come evitare gli anti-pattern SQL.
bloccato 403

Questo errore viene restituito quando BigQuery ha temporaneamente inserito nella lista nera l'operazione che hai tentato di eseguire, in genere per evitare un'interruzione del servizio.

Contatta l'assistenza per ulteriori informazioni.
duplicare 409

Questo errore viene restituito quando si tenta di creare un job, un set di dati o una tabella che esiste già. L'errore viene restituito anche quando la proprietà writeDisposition di un job è impostata su WRITE_EMPTY e la tabella di destinazione a cui accede il job esiste già.

Rinomina la risorsa che stai tentando di creare o modifica il valore di writeDisposition nel job. Per saperne di più, scopri come risolvere l'errore Il job esiste già.
internalError 500

Questo errore viene restituito quando si verifica un errore interno in BigQuery.

Attendi in base ai requisiti di backoff descritti nell'accordo sul livello del servizio BigQuery, poi riprova l'operazione. Se l'errore continua a verificarsi, contatta l'assistenza o segnala un bug utilizzando lo strumento di monitoraggio dei problemi di BigQuery. Puoi anche ridurre la frequenza di questo errore utilizzando le prenotazioni.
non valido 400

Questo errore viene restituito quando è presente un input non valido di qualsiasi tipo diverso da una query non valida, ad esempio campi obbligatori mancanti o uno schema di tabella non valido. Le query non valide restituiscono un errore invalidQuery.
invalidQuery 400

Questo errore viene restituito quando tenti di eseguire una query non valida.

Controlla la query per verificare la presenza di errori di sintassi. Il riferimento alle query contiene descrizioni ed esempi di come creare query valide.
invalidUser 400

Questo errore viene restituito quando tenti di pianificare una query con credenziali utente non valide.

Aggiorna le credenziali utente, come spiegato in Pianificazione delle query.
jobBackendError 400

Questo errore viene restituito quando il job è stato creato correttamente, ma non è riuscito a causa di un errore interno. Potresti visualizzare questo errore in jobs.query o jobs.getQueryResults.

Riprova il job con un nuovo jobId. Se l'errore continua a verificarsi, contatta l'assistenza.
jobInternalError 400

Questo errore viene restituito quando il job è stato creato correttamente, ma non è riuscito a causa di un errore interno. Potresti visualizzare questo errore in jobs.query o jobs.getQueryResults.

Riprova il job con un nuovo jobId. Se l'errore continua a verificarsi, contatta l'assistenza.
jobRateLimitExceeded 400

Questo errore viene restituito quando il job è stato creato correttamente, ma non è andato a buon fine con un errore rateLimitExceeded. Potresti visualizzare questo errore in jobs.query o jobs.getQueryResults.

Utilizza il backoff esponenziale per ridurre la tasso di richieste, quindi riprova a eseguire il job con un nuovo jobId.
notFound 404

Questo errore viene restituito quando fai riferimento a una risorsa (un set di dati, una tabella o un job) che non esiste oppure quando la località nella richiesta non corrisponde a quella della risorsa (ad esempio, la località in cui è in esecuzione un job). Ciò può verificarsi anche quando si utilizzano decoratori di tabelle per fare riferimento a tabelle eliminate di recente trasmesse in streaming.

Correggi i nomi delle risorse, specifica correttamente la posizione o attendi almeno 6 ore dopo lo streaming prima di eseguire una query su una tabella eliminata.
notImplemented 501

Questo errore del job viene restituito quando provi ad accedere a una funzionalità non implementata.

Contatta l'assistenza per ulteriori informazioni.
proxyAuthenticationRequired 407

Questo errore viene restituito tra l'ambiente client e il server proxy quando la richiesta non dispone di credenziali di autenticazione valide per il server proxy. Per ulteriori informazioni, consulta la sezione 407 Proxy Authentication Required.

La risoluzione dei problemi è specifica per il tuo ambiente. Se ricevi questo errore mentre lavori in Java, assicurati di aver impostato le proprietà jdk.http.auth.tunneling.disabledSchemes= e jdk.http.auth.proxying.disabledSchemes= senza valore dopo il segno di uguale.
quotaExceeded 403

Questo errore viene restituito quando il tuo progetto supera una quota BigQuery, una quota personalizzata o quando non hai configurato la fatturazione e hai superato il livello gratuito per le query.

Visualizza la proprietà message dell'oggetto errore per ulteriori informazioni sulla quota superata. Per reimpostare o aumentare una quota BigQuery, contatta l'assistenza. Per modificare una quota personalizzata, invia una richiesta dalla pagina Quote. Se ricevi questo errore utilizzando la sandbox di BigQuery, puoi eseguire l'upgrade dalla sandbox.
Per ulteriori informazioni, vedi Risoluzione dei problemi relativi agli errori di quota di BigQuery.
rateLimitExceeded 403

Questo errore viene restituito se il tuo progetto supera un limite di frequenza a breve termine inviando troppe richieste troppo rapidamente. Ad esempio, consulta i limiti di frequenza delle richieste per i job di query e i limiti di frequenza delle richieste API.

Riduci la tasso di richieste.
Se ritieni che il tuo progetto non abbia superato uno di questi limiti, contatta l'assistenza.
Per ulteriori informazioni, vedi Risoluzione dei problemi relativi agli errori di quota di BigQuery.
resourceInUse 400

Questo errore viene restituito quando tenti di eliminare un set di dati che contiene tabelle o quando tenti di eliminare un job attualmente in esecuzione.

Svuota il set di dati prima di tentare di eliminarlo o attendi il completamento di un job prima di eliminarlo.
resourcesExceeded 400

Questo errore viene restituito quando il job utilizza troppe risorse.

Questo errore viene restituito quando il job utilizza troppe risorse. Per informazioni sulla risoluzione dei problemi, vedi Risolvere i problemi relativi agli errori di superamento delle risorse.
responseTooLarge 403

Questo errore viene restituito quando i risultati della query sono superiori alla dimensione massima della risposta. Alcune query vengono eseguite in più fasi e questo errore viene restituito quando una fase restituisce una dimensione della risposta troppo grande, anche se il risultato finale è inferiore al massimo. Questo errore viene restituito di solito quando le query utilizzano una clausola ORDER BY.

A volte può essere utile aggiungere una clausola LIMIT o rimuovere la clausola ORDER BY. Se vuoi assicurarti che i risultati di grandi dimensioni possano essere restituiti, puoi impostare la proprietà allowLargeResults su true e specificare una tabella di destinazione. Per maggiori informazioni, vedi Scrivere risultati di query di grandi dimensioni.
operazione interrotta 200

Questo codice di stato viene restituito quando un job viene annullato.
tableUnavailable 400

Alcune tabelle BigQuery sono supportate da dati gestiti da altri team di prodotto Google. Questo errore indica che una di queste tabelle non è disponibile.

Quando visualizzi questo messaggio di errore, puoi riprovare a eseguire la richiesta (consulta i suggerimenti per la risoluzione dei problemi relativi a internalError) o contattare il team di prodotto Google che ti ha concesso l'accesso ai suoi dati.
timeout 400

Timeout del job.

Valuta la possibilità di ridurre la quantità di lavoro eseguita dall'operazione in modo che possa essere completata entro il limite impostato. Per ulteriori informazioni, vedi Risoluzione dei problemi relativi a errori di quote e limiti.

Esempio di risposta di errore

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

Calcolare il tasso di richieste non riuscite e l'uptime

La maggior parte degli errori 500 e 503 può essere risolta eseguendo un nuovo tentativo con backoff esponenziale. Nel caso in cui gli errori 500 e 503 persistano, puoi calcolare il tasso complessivo di richieste non riuscite e il tempo di attività corrispondente per confrontarlo con l'accordo sul livello del servizio (SLA) di BigQuery per determinare se il servizio funziona come previsto.

Per calcolare il tasso complessivo di richieste non riuscite negli ultimi 30 giorni, prendi il numero di richieste non riuscite per una specifica chiamata o metodo API negli ultimi 30 giorni e dividilo per il numero totale di richieste per quella chiamata o metodo API negli ultimi 30 giorni. Moltiplica questo valore per 100 per ottenere la percentuale media di richieste non riuscite in 30 giorni.

Ad esempio, puoi eseguire query sui dati di Cloud Logging per ottenere il numero totale di richieste jobs.insert e il numero di richieste jobs.insert non riuscite ed eseguire il calcolo. Puoi anche ottenere i valori del tasso di errore dalla dashboard API o utilizzando Metrics Explorer in Cloud Monitoring. Queste opzioni non includono dati su problemi di rete o routing riscontrati tra il client e BigQuery, pertanto consigliamo anche di utilizzare un sistema di logging e generazione di report lato client per calcoli più precisi del tasso di errore.

Innanzitutto, calcola il 100% meno il tasso complessivo di richieste non riuscite. Se questo valore è maggiore o uguale al valore descritto nello SLA di BigQuery, anche il tempo di attività soddisfa lo SLA di BigQuery. Tuttavia, se questo valore è inferiore a quello descritto nel contratto di servizio, calcola l'uptime manualmente.

Per calcolare l'uptime, devi conoscere il numero di minuti considerati tempi di inattività del servizio. Il tempo di inattività del servizio indica un periodo di un minuto con una percentuale di errori superiore al 10%, calcolata in base alle definizioni dello SLA. Per calcolare l'uptime, prendi il totale dei minuti degli ultimi 30 giorni e sottrai il totale dei minuti in cui il servizio non era disponibile. Dividi il tempo rimanente per i minuti totali degli ultimi 30 giorni e moltiplica questo valore per 100 per ottenere la percentuale di uptime in 30 giorni. Per ulteriori informazioni sulle definizioni e sui calcoli relativi all'SLA , consulta l'accordo sul livello del servizio (SLA) BigQuery.

Se la percentuale di uptime mensile è maggiore o uguale al valore descritto nel contratto di servizio di BigQuery, l'errore è stato probabilmente causato da un problema temporaneo, quindi puoi continuare a riprovare utilizzando il backoff esponenziale.

Se l'uptime è inferiore al valore indicato nel contratto di servizio, contatta l'assistenza per ricevere aiuto e condividi il tasso di errore complessivo osservato e i calcoli dell'uptime.

Errori di autenticazione

Gli errori generati dal sistema di generazione dei token OAuth restituiscono il seguente oggetto JSON, come definito dalla specifica OAuth2.

{"error" : "_description_string_"}

L'errore è accompagnato da un errore HTTP 400 Richiesta errata o da un errore HTTP 401 Non autorizzato. _description_string_ è uno dei codici di errore definiti dalle specifiche OAuth2. Ad esempio:

{"error":"invalid_client"}

Esaminare gli errori

Puoi utilizzare Esplora log per visualizzare gli errori di autenticazione per job, utenti o altri ambiti specifici. Di seguito sono riportati esempi di filtri di Esplora log che puoi utilizzare per esaminare gli errori di autenticazione:

  • Cerca i job non riusciti con problemi di autorizzazione negli audit log Policy Denied:

    resource.type="bigquery_resource"
protoPayload.status.message=~"Access Denied"
logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"

    Sostituisci PROJECT_ID con l'ID del progetto che contiene la risorsa.

  • Cerca un utente o un account di servizio specifico utilizzato per l'autenticazione:

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

    Sostituisci EMAIL con l'indirizzo email dell'utente o delaccount di serviziot.

  • Cerca le modifiche alle policy di Identity and Access Management nei log di controllo delle attività di amministrazione:

    protoPayload.methodName=~"SetIamPolicy"
logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"

  • Cerca le modifiche a un set di dati BigQuery specifico negli audit log per l'accesso ai dati:

    resource.type="bigquery_resource"
protoPayload.resourceName="projects/PROJECT_ID/datasets/DATASET_ID"
logName=projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access

    Sostituisci DATASET_ID con l'ID del set di dati contenente la risorsa.

Messaggi di errore di connettività

La tabella seguente elenca i messaggi di errore che potresti visualizzare a causa di problemi di connettività intermittenti quando utilizzi le librerie client o chiami l'API BigQuery dal tuo codice:

Messaggio di errore Libreria client o API Risoluzione dei problemi
com.google.cloud.bigquery.BigQueryException: Read timed out Java Imposta un valore di timeout maggiore.
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 Implementa un meccanismo di ripetizione e imposta un valore di timeout più elevato.
javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake Java Implementa un meccanismo di ripetizione e imposta un valore di timeout più elevato.
BrokenPipeError: [Errno 32] Broken pipe Python Implementa un meccanismo di ripetizione. Per saperne di più su questo errore, consulta BrokenPipeError.
Connessione interrotta. RemoteDisconnected('Remote end closed connection without response' Python Imposta un valore di timeout maggiore.
SSLEOFError (EOF occurred in violation of protocol) Python Questo errore viene restituito anziché un errore HTTP 413 (ENTITY_TOO_LARGE). Riduci le dimensioni della richiesta.
TaskCanceledException: un'attività è stata annullata Libreria .NET Aumenta il valore del timeout sul lato client.
google.api_core.exceptions.PreconditionFailed: 412 PATCH Python Questo errore viene restituito durante il tentativo di aggiornamento di una risorsa tabella utilizzando una richiesta HTTP. Assicurati che l'ETag nell'intestazione HTTP non sia obsoleta. Per le operazioni a livello di tabella o set di dati, assicurati che la risorsa non sia stata modificata dall'ultima volta che è stata creata un'istanza e ricrea l'oggetto, se necessario.
Impossibile stabilire una nuova connessione: [Errno 110] Connection timed out Librerie client Questo errore viene restituito quando questa richiesta ha raggiunto la fine del file (EOF) durante lo streaming o la lettura dei dati da BigQuery. Implementa un meccanismo di ripetizione e imposta un valore di timeout più elevato.
socks.ProxyConnectionError: Error connecting to HTTP proxy :8080: [Errno 110] Connection timed out Librerie client Risolvi i problemi relativi allo stato e alle impostazioni del proxy. Implementa un meccanismo di ripetizione e imposta un valore di timeout più elevato.
Ricezione di un EOF imprevisto o di 0 byte dallo stream di trasporto Librerie client Implementa un meccanismo di ripetizione e imposta un valore di timeout più elevato.

Google Cloud Messaggi di errore della console

La tabella seguente elenca i messaggi di errore che potresti visualizzare mentre lavori nella consoleGoogle Cloud .

Messaggio di errore Descrizione Risoluzione dei problemi
Risposta di errore sconosciuta dal server. Questo errore viene visualizzato quando la console Google Cloud riceve un errore sconosciuto dal server, ad esempio quando fai clic su un set di dati o su un altro tipo di link e la pagina non può essere visualizzata. Passa alla modalità di navigazione in incognito o privata del browser e ripeti l'azione che ha generato l'errore. Se non si verificano errori in modalità di navigazione in incognito, l'errore potrebbe essere dovuto a un'estensione del browser, ad esempio un blocco degli annunci. Disattiva le estensioni del browser quando non sei in modalità di navigazione in incognito e verifica se il problema si risolve.