Mensajes de error

En este documento, se describen los mensajes de error que puedes encontrar cuando trabajas con BigQuery, incluidos los códigos de error de HTTP y los pasos sugeridos para solucionar problemas.

Para obtener más información sobre los errores de consulta, consulta Soluciona errores de consulta.

Para obtener más información sobre los errores de inserción de transmisión, consulta Soluciona problemas de inserción de transmisión.

Tabla de errores

Las respuestas de la API de BigQuery incluyen un código de error de HTTP y un objeto de errores en el cuerpo de la respuesta. Un objeto de error generalmente es uno de los siguientes:

La columna Mensaje de error en la siguiente tabla se asigna a la propiedad reason en un objeto ErrorProto.

Esta tabla no incluye todos los errores de HTTP posibles o cualquier otro error de red. Por lo tanto, no asumas que hay un objeto de error en cada respuesta de error de BigQuery. Además, es posible que recibas diferentes errores o objetos de error si usas las bibliotecas cliente de Cloud para la API de BigQuery. Para obtener más información, consulta Bibliotecas cliente de la API de BigQuery.

Si recibes un código de respuesta HTTP que no aparece en la siguiente tabla, el código de respuesta indica un problema o un resultado esperado con la solicitud HTTP. Los códigos de respuesta en el rango 5xx indican un error del servidor. Si recibes un código de respuesta 5xx, vuelve a intentar la solicitud más tarde. En algunos casos, un servidor intermedio, como un proxy, puede devolver un código de respuesta 5xx. Examina el cuerpo y los encabezados de la respuesta para obtener detalles sobre el error. Para obtener una lista completa de los códigos de respuesta HTTP, consulta Códigos de respuesta HTTP.

Si usas la herramienta de línea de comandos de bq para verificar el estado del trabajo, según la configuración predeterminada, no se muestra el objeto de error. Para ver el objeto de error y la propiedad reason correspondiente que se asigna a la siguiente tabla, usa la marca --format=prettyjson. Por ejemplo, bq --format=prettyjson show -j *<job id>*. Para ver el registro detallado de la herramienta bq, usa --apilog=stdout. Para obtener más información sobre cómo solucionar problemas de la herramienta bq, consulta Depuración.

Mensaje de error Código HTTP Descripción Soluciona problemas
accessDenied 403

Este error se muestra cuando intentas acceder a un recurso, como un conjunto de datos, una tabla, una vista o un trabajo al que no tienes acceso. También se muestra cuando intentas modificar un objeto de solo lectura.

Comunícate con el propietario del recurso y solicita acceso al recurso para el usuario identificado por el valor principalEmail en el registro de auditoría del error.
attributeError 400

Este error se devuelve cuando hay un problema con el código de usuario en el que se llama a un atributo de objeto determinado, pero no existe.

Asegúrate de que el objeto con el que estás trabajando tenga el atributo al que intentas acceder. Para obtener más información sobre este error, consulta AttributeError.
backendError 500, 502, 503 o 504

Este error indica que el servicio no está disponible en este momento. Esto puede suceder debido a varios problemas transitorios, incluidos los siguientes:

  • Aumento de la demanda del servicio: Los aumentos repentinos de la demanda, como los momentos de uso máximo, pueden provocar una reducción de carga para proteger la calidad del servicio para todos los usuarios de BigQuery. Para evitar que el sistema se sature, BigQuery puede devolver errores 500 o 503 para una pequeña parte de las solicitudes.
  • Problemas de red: La naturaleza distribuida de BigQuery significa que los datos suelen transferirse entre diferentes componentes o máquinas en el sistema. Varios problemas intermitentes de conectividad de red pueden hacer que BigQuery devuelva un error 5xx, incluidos los errores de protocolo de enlace SSL o de infraestructura de red entre el usuario y Google Cloud.
  • Agotamiento de recursos: BigQuery tiene varios límites de recursos internos para proteger el rendimiento general del servicio de un solo usuario o un solo trabajo que consuma demasiados recursos. BigQuery implementa la reducción de carga para abordar el agotamiento de recursos.
  • Errores de backend: En casos excepcionales, un problema interno en uno de los componentes de BigQuery puede generar un error 500 o 503 que se devuelve al cliente.

Los errores 5xx son problemas del servicio y el cliente no tiene forma de corregirlos ni controlarlos. Desde el lado del cliente, para mitigar el impacto de los errores 5xx, debes volver a intentar tus solicitudes con retiradas exponenciales truncadas. Para obtener más información sobre las retiradas exponenciales, consulta Retirada exponencial. Sin embargo, existen dos casos especiales en la solución de este error: el de las llamadas jobs.get y el de las llamadas jobs.insert.

jobs.get llamadas

  • Si recibiste un error 503 cuando sondeaste jobs.get, espera unos segundos y vuelve a sondear.
  • Si el trabajo se completa, pero incluye un objeto de error que contiene backendError, significa que el trabajo falló. Puedes volver a intentar el trabajo de forma segura sin preocuparte por la coherencia de los datos.

Llamadas a jobs.insert
Si recibes este error cuando realizas una llamada a jobs.insert, no queda claro si el trabajo se completó correctamente. En este caso, deberás volver a intentarlo.

Si los reintentos no son eficaces y los problemas persisten, puedes calcular la tasa de solicitudes con errores y comunicarte con el equipo de asistencia.
Además, si observas que una solicitud específica a BigQuery falla de forma persistente con un error 5xx, incluso cuando se vuelve a intentar con la retirada exponencial en varios intentos de reinicio del flujo de trabajo, debes derivar este problema al equipo de asistencia para solucionarlo desde el lado de BigQuery, independientemente de la tasa de error general calculada. Asegúrate de comunicar con claridad el impacto en el negocio para que el problema se pueda clasificar de forma correcta.
badRequest 400

El error 'UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported' puede ocurrir cuando algunas filas transmitidas recientemente en una tabla pueden no estar disponibles para las operaciones DML (DELETE, UPDATE,MERGE), por lo general, durante unos pocos minutos, pero en casos excepcionales, hasta 90 minutos. Para obtener más información, consulta Disponibilidad de datos de transmisión y Limitaciones de DML.

Espera unos minutos y vuelve a intentarlo, o filtra la sentencia para que solo opere en datos más antiguos que estén fuera del búfer de transmisión. Para ver si los datos están disponibles para las operaciones de DML de tabla, verifica la respuesta tables.get de la sección streamingBuffer. Si la sección streamingBuffer está ausente, los datos de la tabla están disponibles para las operaciones de DML. También puedes usar el campo streamingBuffer.oldestEntryTime para identificar la antigüedad de los registros en el búfer de transmisión.

Como alternativa, considera transmitir datos con la API de BigQuery Storage Write (gRPC), que no tiene esta limitación.
billingNotEnabled 403

Se muestra este error cuando la facturación no está habilitada para el proyecto.

Habilita la facturación para el proyecto en la consola deGoogle Cloud .
billingTierLimitExceeded 400

Este error se muestra cuando el valor de statistics.query.billingTier para un trabajo on demand supera los 100. Esto ocurre cuando las consultas on demand usan demasiada CPU en relación con la cantidad de datos analizados. Para obtener instrucciones sobre cómo inspeccionar los detalles de un trabajo de inspección, consulta Administra trabajos.

Este error suele ser el resultado de la ejecución de uniones cruzadas ineficientes, ya sea de forma explícita o implícita, por ejemplo, debido a una condición de unión inexacta. Estos tipos de consultas no son adecuadas para los precios según demanda debido al alto consumo de recursos y, en general, es posible que no escalen bien. Puedes optimizar la consulta o cambiar para usar el modelo de precios basado en la capacidad (ranuras) con el objetivo de resolver este error. Para obtener información sobre la optimización de consultas, consulta Cómo evitar antipatrones de SQL.
blocked 403

Se muestra este error cuando BigQuery pone en la lista de bloqueo de manera temporal la operación que intentaste realizar, por lo general, para evitar una suspensión del servicio.

Comunícate con el equipo de asistencia para obtener más información.
duplicar 409

Este error se muestra cuando intentas crear un trabajo, un conjunto de datos o una tabla que ya existe. El error también se muestra cuando la propiedad writeDisposition de un trabajo se establece en WRITE_EMPTY y la tabla de destino a la que accede el trabajo ya existe.

Cambia el nombre del recurso que intentas crear o cambia el valor de writeDisposition en el trabajo. Para obtener más información, consulta cómo solucionar el error El trabajo ya existe.
internalError 500

Este error se muestra cuando se produce un error interno en BigQuery.

Espera según los requisitos de retirada que se describen en el Acuerdo de Nivel de Servicio de BigQuery y, luego, vuelve a intentar la operación. Si el error persiste, comunícate con el equipo de asistencia o informa un error con la herramienta de seguimiento de errores de BigQuery. También puedes reducir la frecuencia de este error con las reservas.
no válido 400

Se muestra este error cuando hay algún tipo de entrada no válida que no es una consulta no válida, como campos obligatorios faltantes o un esquema de tabla no válido. Las consultas no válidas muestran un error invalidQuery.
invalidQuery 400

Se muestra este error cuando intentas ejecutar una consulta no válida.

Comprueba tu consulta en busca de errores de sintaxis. La referencia de consulta contiene descripciones y ejemplos de cómo crear consultas válidas.
invalidUser 400

Este error se muestra cuando intentas programar una consulta con credenciales de usuario no válidas.

Actualiza las credenciales del usuario, como se explica en Programa consultas.
jobBackendError 400

Se muestra este error cuando el trabajo se creó correctamente, pero falló con un error interno. Es posible que veas este error en jobs.query o jobs.getQueryResults.

Vuelve a intentar el trabajo con una jobId nueva. Si el error persiste, comunícate con el equipo de asistencia.
jobInternalError 400

Se muestra este error cuando el trabajo se creó correctamente, pero falló con un error interno. Es posible que veas este error en jobs.query o jobs.getQueryResults.

Vuelve a intentar el trabajo con una jobId nueva. Si el error persiste, comunícate con el equipo de asistencia.
jobRateLimitExceeded 400

Este error se muestra cuando el trabajo se creó correctamente, pero falló con un error rateLimitExceeded. Es posible que veas este error en jobs.query o jobs.getQueryResults.

Usa la retirada exponencial para reducir el porcentaje de solicitudes y, luego, vuelve a intentar el trabajo con un jobId nuevo.
notFound 404

Se muestra este error cuando haces referencia a un recurso (un conjunto de datos, una tabla o un trabajo) que no existe o cuando la ubicación de la solicitud no coincide con la ubicación del recurso (por ejemplo, la ubicación en la que se ejecuta un trabajo). Esto también puede ocurrir cuando usas decoradores de instantáneas para hacer referencia a las tablas borradas que recibieron transmisiones hace poco.

Corrige los nombres de los recursos, especifica la ubicación de forma correcta o espera al menos 6 horas después de la transmisión antes de consultar una tabla borrada.
notImplemented 501

Este error de trabajo se muestra cuando intentas acceder a una función que no está implementada.

Comunícate con el equipo de asistencia para obtener más información.
proxyAuthenticationRequired 407

Este error se devuelve entre el entorno del cliente y el servidor proxy cuando la solicitud no tiene credenciales de autenticación válidas para el servidor proxy. Para obtener más información, consulta 407 Se requiere autenticación del proxy.

La solución de problemas es específica de tu entorno. Si recibes este error mientras trabajas en Java, asegúrate de haber configurado las propiedades jdk.http.auth.tunneling.disabledSchemes= y jdk.http.auth.proxying.disabledSchemes= sin ningún valor después del signo igual.
quotaExceeded 403

Este error se muestra cuando tu proyecto excede una cuota de BigQuery, una cuota personalizada o cuando no configuraste la facturación y excediste el nivel gratuito para las consultas.

Consulta la propiedad message del objeto de error para obtener más información sobre qué cuota se superó. Para restablecer o aumentar una cuota de BigQuery, comunícate con el equipo de asistencia. Para modificar una cuota personalizada, envía una solicitud desde la página Cuotas. Si recibes este error cuando usas la zona de pruebas de BigQuery, puedes actualizar desde la zona de pruebas.
Si deseas obtener más información, consulta Solución de problemas de errores de cuota de BigQuery.
rateLimitExceeded 403, 429

Este error se muestra si tu proyecto excede un límite de frecuencia a corto plazo cuando se envían demasiadas solicitudes con demasiada rapidez. Por ejemplo, consulta los límites de frecuencia para los trabajos de consulta y los límites de frecuencia para las solicitudes a la API.

Disminuye el porcentaje de solicitudes.
Si crees que tu proyecto no superó uno de estos límites, comunícate con el equipo de asistencia.
Si deseas obtener más información, consulta Solución de problemas de errores de cuota de BigQuery.
resourceInUse 400

Este error se muestra cuando intentas borrar un conjunto de datos que contiene tablas o cuando intentas borrar un trabajo que se está ejecutando.

Vacía el conjunto de datos antes de intentar borrarlo o espera a que se complete un trabajo antes de borrarlo.
resourcesExceeded 400

Se muestra este error cuando tu trabajo usa demasiados recursos.

Se muestra este error cuando tu trabajo usa demasiados recursos. Para obtener información sobre la solución de problemas, consulta Soluciona problemas de errores de recursos excedidos.
responseTooLarge 403

Este error se muestra cuando los resultados de tu consulta son más grandes que el tamaño máximo de respuesta. Algunas consultas se ejecutan en varias etapas, y este error se muestra cuando cualquier etapa devuelve un tamaño de respuesta demasiado grande, incluso si el resultado final es menor que el máximo. Por lo general, este error se muestra cuando las consultas usan una cláusula ORDER BY.

A veces, agregar una cláusula LIMIT o quitar la cláusula ORDER BY sirve de ayuda. Si deseas garantizar que se puedan mostrar resultados grandes, puedes establecer la propiedad allowLargeResults en true y especificar una tabla de destino. Para obtener más información, consulta Escribe resultados de consultas grandes.
detenida 200

Se muestra este código de estado cuando se cancela un trabajo.
tableUnavailable 400

Ciertas tablas de BigQuery están respaldadas por datos que administran otros equipos de productos de Google. Este error indica que una de estas tablas no está disponible.

Cuando encuentres este mensaje de error, puedes volver a intentar la solicitud (consulta las sugerencias para solucionar problemas de internalError) o comunicarte con el equipo de producto de Google que te otorgó acceso a sus datos.
timeout 400

Se agotó el tiempo de espera del trabajo.

Considera reducir la cantidad de trabajo que realiza tu operación para que pueda completarse dentro del límite establecido. Para obtener más información, consulta Soluciona problemas de cuota y limita errores.

Muestra de respuesta de error

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

Calcula la tasa de solicitudes con errores y el tiempo de actividad

La mayoría de los errores 500 y 503 se pueden resolver si se vuelve a intentar con una retirada exponencial. En caso de que los errores 500 y 503 sigan persistiendo, puedes calcular la tasa general de solicitudes con errores y el tiempo de actividad correspondiente para compararlo con el Acuerdo de Nivel de Servicio (ANS) de BigQuery y determinar si el servicio funciona como se espera.

Para calcular la tasa general de solicitudes con errores durante los últimos 30 días, toma la cantidad de solicitudes con errores de una llamada a la API o un método específicos de los últimos 30 días y divídela por la cantidad total de solicitudes de esa llamada a la API o ese método de la API de los últimos 30 días. Multiplica este valor por 100 para obtener el porcentaje promedio de solicitudes con errores durante 30 días.

Por ejemplo, puedes consultar los datos de Cloud Logging para obtener la cantidad total de solicitudes de jobs.insert y la cantidad de solicitudes de jobs.insert con errores, y realizar el cálculo. También puedes obtener los valores de la tasa de errores en el panel de la API o con el Explorador de métricas en Cloud Monitoring. Estas opciones no incluirán datos sobre los problemas de red o enrutamiento que se encuentren entre el cliente y BigQuery, por lo que también recomendamos usar un sistema de registro y generación de informes del cliente para obtener cálculos más precisos de la tasa de fallas.

Primero, resta la tasa general de solicitudes con errores del 100%. Si este valor es mayor o igual que el valor descrito en el ANS de BigQuery, el tiempo de actividad también cumple con el ANS de BigQuery. Sin embargo, si este valor es menor que el valor descrito en el ANS, calcula el tiempo de actividad de forma manual.

Para calcular el tiempo de actividad, debes conocer la cantidad de minutos que se consideran tiempo de inactividad del servicio. El tiempo de inactividad del servicio se refiere a un período de un minuto con una tasa de errores superior al 10% calculada según las definiciones del ANS. Para calcular el tiempo de actividad, toma el total de minutos de los últimos 30 días y resta el total de minutos que el servicio estuvo inactivo. Divide el tiempo restante por la cantidad total de minutos de los últimos 30 días y multiplica este valor por 100 para obtener el porcentaje de tiempo de actividad durante 30 días. Para obtener más información sobre las definiciones y los cálculos relacionados con el ANS , consulta el Acuerdo de Nivel de Servicio (ANS) de BigQuery.

Si tu porcentaje de tiempo de actividad mensual es mayor o igual que el valor descrito en el ANS de BigQuery, lo más probable es que el error se haya producido por un problema transitorio, por lo que puedes seguir reintentando con la retirada exponencial.

Si el tiempo de actividad es inferior al valor que se presenta en el ANS, comunícate con el equipo de asistencia para obtener ayuda y comparte la tasa de errores general observada y los cálculos del tiempo de actividad.

Errores de autenticación

Los errores que arroja el sistema de generación de tokens de OAuth devuelven el siguiente objeto JSON, como se define en la especificación de OAuth2.

{"error" : "_description_string_"}

El error se acompaña de un error HTTP 400 de solicitud incorrecta o un error HTTP 401 de no autorizado. _description_string_ es uno de los códigos de error definidos por la especificación de OAuth 2.0. Por ejemplo:

{"error":"invalid_client"}

Revisa los errores

Puedes usar el explorador de registros para ver los errores de autenticación de trabajos, usuarios o otros alcances específicos. A continuación, se muestran ejemplos de filtros del Explorador de registros que puedes usar para revisar los errores de autenticación:

  • Busca trabajos fallidos con problemas de permisos en los registros de auditoría de política denegada:

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

    Reemplaza PROJECT_ID por el ID del proyecto que contiene el recurso.

  • Busca un usuario o una cuenta de servicio específicos que se usen para la autenticación:

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

    Reemplaza EMAIL por la dirección de correo electrónico del usuario o de la cuenta de servicio.

  • Busca cambios en la política de Identity and Access Management en los registros de auditoría de actividad del administrador:

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

  • Busca cambios en un conjunto de datos específico de BigQuery en los registros de auditoría de acceso a los datos:

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

    Reemplaza DATASET_ID por el ID del conjunto de datos que contiene el recurso.

Mensajes de error de conectividad

En la siguiente tabla, se enumeran los mensajes de error que puedes ver debido a problemas de conectividad intermitente cuando usas las bibliotecas cliente o llamas a la API de BigQuery desde tu código:

Mensaje de error Biblioteca cliente o API Soluciona problemas
com.google.cloud.bigquery.BigQueryException: Read timed out Java Establece un valor de tiempo de espera mayor.
Se cerró la conexión: javax.net.ssl.SSLException: java.net.SocketException: Se restableció la conexión en com.google.cloud.bigquery.spi.v2.HttpBigQueryRpc.translate(HttpBigQueryRpc.java:115) Java Implementa un mecanismo de reintento y configura un valor de tiempo de espera mayor.
javax.net.ssl.SSLHandshakeException: el host remoto finalizó el protocolo de enlace Java Implementa un mecanismo de reintento y configura un valor de tiempo de espera mayor.
BrokenPipeError: [Errno 32] Broken pipe Python Implementa un mecanismo de reintento. Para obtener más información sobre este error, consulta BrokenPipeError.
Se anuló la conexión. RemoteDisconnected('Remote end closed connection without response' Python Establece un valor de tiempo de espera mayor.
SSLEOFError (se produjo un EOF que incumple el protocolo) Python Este error se devuelve en lugar de un error HTTP 413 (ENTITY_TOO_LARGE). Reduce el tamaño de la solicitud.
TaskCanceledException: se canceló una tarea Biblioteca de .NET Aumenta el valor de tiempo de espera del cliente.
google.api_core.exceptions.PreconditionFailed: 412 PATCH Python Este error se muestra cuando se intenta actualizar un recurso de tabla con una solicitud HTTP. Asegúrate de que la ETag en el encabezado HTTP no esté desactualizada. En el caso de las operaciones a nivel de tabla o conjunto de datos, asegúrate de que el recurso no haya cambiado desde la última vez que se creó una instancia y vuelve a crear el objeto si es necesario.
No se pudo establecer una conexión nueva: [Errno 110] Se agotó el tiempo de espera de la conexión Bibliotecas cliente Este error se muestra cuando esta solicitud alcanza el final del archivo (EOF) cuando se transmiten o leen datos de BigQuery. Implementa un mecanismo de reintento y configura un valor de tiempo de espera mayor.
socks.ProxyConnectionError: Error connecting to HTTP proxy :8080: [Errno 110] Connection timed out Bibliotecas cliente Soluciona problemas relacionados con el estado y la configuración del proxy. Implementa un mecanismo de reintento y configura un valor de tiempo de espera mayor.
Se recibió un EOF inesperado o 0 bytes del flujo de transporte Bibliotecas cliente Implementa un mecanismo de reintento y configura un valor de tiempo de espera mayor.

Mensajes de error de la consola deGoogle Cloud

En la siguiente tabla, se enumeran los mensajes de error que pueden aparecer cuando trabajas en la consola deGoogle Cloud .

Mensaje de error Descripción Soluciona problemas
Respuesta de error desconocida del servidor Este error se muestra cuando la consola de Google Cloud recibe un error desconocido del servidor, por ejemplo, cuando haces clic en un conjunto de datos o en otro tipo de vínculo, y la página no puede mostrarse. Cambia al modo incógnito o privado del navegador, y repite la acción que generó el error. Si no se muestra ningún error en el modo Incógnito, el error puede deberse a una extensión del navegador, como un bloqueador de anuncios. Inhabilita las extensiones del navegador sin usar el modo Incógnito y verifica si se resolvió el problema.