오류 메시지
이 문서는 BigQuery로 작업할 때 발생할 수 있는 오류 메시지에 대해 설명하며 HTTP 오류 코드 및 권장되는 문제 해결 단계를 포함하고 있습니다.
쿼리 오류에 대한 자세한 내용은 쿼리 오류 문제 해결을 참고하세요.
스트리밍 삽입 오류에 대한 자세한 내용은 스트리밍 삽입 문제 해결을 참고하세요.
오류 표
BigQuery API의 응답에는 HTTP 오류 코드 및 응답 본문의 오류 객체가 포함됩니다. 오류 객체는 일반적으로 다음 중 하나입니다.
ErrorProto
객체의 배열을 포함하는errors
객체- 단일
ErrorProto
객체를 포함하는errorResults
객체
다음 표의 오류 메시지 열은 ErrorProto
객체의 reason
속성에 매핑됩니다.
이 표에는 모든 가능한 HTTP 오류 또는 다른 네트워킹 오류가 포함되지 않습니다. 따라서 오류 객체가 BigQuery의 모든 오류 응답에 포함된다고 추정해서는 안 됩니다. 또한 BigQuery API에 Cloud 클라이언트 라이브러리를 사용하는 경우 다른 오류 또는 오류 객체가 수신될 수 있습니다. 자세한 내용은 BigQuery API 클라이언트 라이브러리를 참조하세요.
다음 표에 없는 HTTP 응답 코드를 받는 경우, 해당 응답 코드는 문제 또는 HTTP 요청의 예상 결과를 나타냅니다. 5xx
범위의 응답 코드는 서버 측 오류를 나타냅니다. 5xx
응답 코드를 수신하면 나중에 요청을 다시 시도하세요. 경우에 따라 프록시와 같은 중간 서버에서 5xx
응답 코드를 반환할 수 있습니다. 오류에 대한 자세한 내용은 응답 본문과 응답 헤더를 검토하세요. 전체 HTTP 응답 코드 목록은 HTTP 응답 코드를 참조하세요.
bq 명령줄 도구를 사용하여 작업 상태를 확인하는 경우, 오류 객체는 기본적으로 반환되지 않습니다. 오류 객체 및 다음 표에 매핑되는 해당 reason
속성을 보려면 --format=prettyjson
플래그를 사용합니다. 예를 들면 bq --format=prettyjson show -j
*<job id>*
입니다. bq 도구의 상세 로깅을 보려면 --apilog=stdout
를 사용합니다. bq 도구 문제 해결에 대한 자세한 내용은 디버깅을 참조하세요.
오류 메시지 | HTTP 코드 | 설명 | 문제 해결 |
---|---|---|---|
accessDenied | 403 |
이 오류는 액세스할 권한이 없는 데이터 세트, 테이블, 뷰, 작업과 같은 리소스에 액세스하려고 하면 반환됩니다. 읽기 전용 객체를 수정하려고 시도하는 경우에도 이 오류가 반환됩니다. |
리소스 소유자에게 연락하여 오류의 감사 로그에서 |
attributeError | 400 |
이 오류는 특정 객체 속성이 호출되지만 존재하지 않는 사용자 코드에 문제가 있을 때 반환됩니다. |
작업 중인 객체에 액세스하려는 속성이 있는지 확인합니다. 이 오류에 관한 자세한 내용은 AttributeError를 참고하세요. |
backendError | 500, 503 또는 504 |
이 오류는 현재 서비스를 사용할 수 없음을 나타냅니다. 이는 다음과 같은 여러 일시적인 문제로 인해 발생할 수 있습니다.
|
5xx 오류는 서비스 측 문제이며 클라이언트가 이를 수정하거나 제어할 방법이 없습니다. 클라이언트 측에서 5xx 오류의 영향을 완화하려면 잘린 지수 백오프를 사용하여 요청을 재시도해야 합니다. 지수 백오프에 관한 자세한 내용은 지수 백오프를 참고하세요. 그러나 이 오류의 문제 해결을 위한 두 가지 특수한 사례(
재시도가 효과가 없고 문제가 지속되면 실패한 요청의 비율을 계산하고 지원팀에 문의하세요. |
badRequest | 400 |
테이블에서 최근에 스트리밍된 일부 행을 일반적으로 몇 분 동안, 드물게는 최대 90분 동안 DML 작업( |
몇 분 정도 기다린 후 다시 시도하거나 스트리밍 버퍼 외부에 있는 이전 데이터에만 작동하도록 명령문을 필터링하세요. 테이블 DML 작업에 데이터를 사용할 수 있는지 확인하려면 streamingBuffer 섹션의 또는 이 제한이 없는 BigQuery Storage Write API를 사용하여 데이터를 스트리밍하는 것이 좋습니다. |
billingNotEnabled | 403 |
프로젝트에서 청구가 사용 설정되지 않은 경우 이 오류가 반환됩니다. |
Google Cloud 콘솔에서 프로젝트의 결제를 사용 설정합니다. |
billingTierLimitExceeded | 400 |
이 오류는 주문형 작업의 |
이 오류는 예를 들어 부정확한 조인 조건으로 인해 명시적으로 또는 암시적으로 비효율적인 교차 조인을 실행하는 경우에 가장 자주 발생합니다. 이러한 유형의 쿼리는 리소스 소비가 많아서 주문형 가격 책정에 적합하지 않으며 일반적으로 확장에 적합하지 않을 수 있습니다. 쿼리를 최적화하거나 용량 기반(슬롯) 가격 책정 모델을 사용하도록 전환하여 이 오류를 해결할 수 있습니다. 쿼리 최적화에 대한 자세한 내용은 SQL 안티패턴 방지를 참조하세요. |
차단됨 | 403 |
이 오류는 일반적으로 서비스 중단을 방지하기 위해 BigQuery에서 사용자가 시도하는 작업을 일시적으로 차단 목록에 포함하는 경우에 반환됩니다. |
자세한 내용은 지원팀에 문의하세요. |
duplicate | 409 |
이 오류는 이미 존재하는 작업, 데이터 세트, 테이블을 만들려고 시도할 때 반환됩니다. 또한 작업의 |
만들려는 리소스의 이름을 바꾸거나 작업의 |
internalError | 500 |
이 오류는 BigQuery 내에서 내부 오류가 발생하면 반환됩니다. |
BigQuery 서비스수준계약에 설명된 백오프 요구사항에 따라 기다린 후 작업을 다시 시도하세요. 오류가 계속 발생하면 지원팀에 문의하거나 BigQuery Issue Tracker를 사용하여 버그를 신고합니다. 예약을 사용하여 이 오류의 빈도를 줄일 수도 있습니다. |
유효하지 않음 | 400 |
이 오류는 필수 입력란 누락 또는 잘못된 테이블 스키마와 같은, 잘못된 쿼리 외에 잘못된 입력이 있는 경우에 반환됩니다.
잘못된 쿼리는 |
|
invalidQuery | 400 |
이 오류는 잘못된 쿼리를 시도하는 경우 반환됩니다. |
쿼리에서 문법 오류를 확인하세요. 쿼리 참조에는 유효한 쿼리를 작성하는 방법에 대한 설명과 예가 포함되어 있습니다. |
invalidUser | 400 |
이 오류는 잘못된 사용자 인증 정보를 사용하여 쿼리를 예약하려고 시도할 때 반환됩니다. |
쿼리 예약에 설명된 대로 사용자 인증 정보를 새로고침합니다. |
jobBackendError | 400 |
이 오류는 작업이 성공적으로 생성되었지만 내부 오류로 실패한 경우에 반환됩니다. 이 오류는 |
새 |
jobInternalError | 400 |
이 오류는 작업이 성공적으로 생성되었지만 내부 오류로 실패한 경우에 반환됩니다. 이 오류는 |
새 |
jobRateLimitExceeded | 400 |
이 오류는 작업이 성공적으로 생성되었지만 rateLimitExceeded 오류로 실패한 경우에 반환됩니다. 이 오류는 |
지수 백오프를 사용하여 요청 비율을 줄인 다음 새 |
notFound | 404 |
이 오류는 존재하지 않는 리소스(데이터 세트, 테이블 또는 작업)를 참조하거나 요청의 위치가 리소스 위치(예: 작업이 실행되는 위치)와 일치하지 않으면 반환됩니다. 테이블 데코레이터를 사용하여 최근에 스트리밍되었지만 삭제된 테이블을 참조하는 경우에도 이 오류가 발생할 수 있습니다. |
리소스 이름을 수정하거나 위치를 올바르게 지정하거나 삭제된 테이블을 쿼리하기 전에 스트리밍 후 최소 6시간을 기다립니다. |
notImplemented | 501 |
이 작업 오류는 구현되지 않은 기능에 액세스하려고 시도하는 경우 반환됩니다. |
자세한 내용은 지원팀에 문의하세요. |
proxyAuthenticationRequired | 407 |
이 오류는 요청에 프록시 서버에 대한 유효한 인증 사용자 인증 정보가 없을 때 클라이언트 환경과 프록시 서버 간에 반환됩니다. 자세한 내용은 407 프록시 인증 필요를 참고하세요. |
문제 해결은 환경에 따라 다릅니다. Java에서 작업하는 중에 이 오류가 표시되면 등호 뒤에 값이 없는 |
quotaExceeded | 403 |
이 오류는 프로젝트가 BigQuery 할당량, 커스텀 할당량을 초과하는 경우 또는 청구를 설정하지 않고 무료 쿼리 등급을 초과하는 경우에 반환됩니다. |
초과된 할당량에 대한 자세한 내용은 오류 객체의 |
rateLimitExceeded | 403 |
이 오류는 프로젝트가 과다한 요청을 지나치게 빠른 속도로 전송함으로써 단기 비율 제한을 초과하는 경우 반환됩니다. 예를 들어 쿼리 작업의 비율 제한과 API 요청의 비율 제한을 참조하세요. |
요청 속도를 낮추세요. |
resourceInUse | 400 |
이 오류는 테이블이 포함된 데이터 세트를 삭제하려고 시도하거나 현재 실행 중인 작업을 삭제하려고 시도하는 경우 반환됩니다. |
데이터 세트를 삭제하기 전에 비우거나 작업이 완료될 때까지 기다린 후에 데이터 세트를 삭제합니다. |
resourcesExceeded | 400 |
이 오류는 작업에서 과다한 리소스를 사용하는 경우 반환됩니다. |
이 오류는 작업에서 과다한 리소스를 사용하는 경우 반환됩니다. 문제 해결 정보는 리소스 초과 오류 문제 해결을 참고하세요. |
responseTooLarge | 403 |
이 오류는 쿼리 결과가 최대 응답 크기보다 큰 경우에 반환됩니다. 일부 쿼리는 여러 단계로 실행되며, 어느 단계에서 지나치게 큰 응답 크기를 반환하는 경우 최종 결과가 최대값보다 작더라도 이 오류가 반환됩니다. 이 오류는 쿼리에서 |
|
중지됨 | 200 |
이 상태 코드는 작업이 취소되는 경우 반환됩니다. |
|
tableUnavailable | 400 |
특정 BigQuery 테이블에는 다른 Google 제품팀이 관리하는 데이터가 사용됩니다. 이 오류는 이러한 테이블 중 하나를 사용할 수 없음을 나타냅니다. |
이 오류 메시지가 표시되면 요청을 다시 시도하거나(internalError 문제 해결 제안 참조) 데이터 액세스 권한을 부여한 Google 제품팀에 문의합니다. |
timeout | 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일 동안의 전체 실패 요청 비율을 계산하려면 지난 30일 동안의 특정 API 호출 또는 메서드의 실패 요청 수를 지난 30일 동안의 해당 API 호출 또는 메서드의 총 요청 수로 나눕니다. 이 값에 100을 곱하면 30일 동안의 실패한 요청의 평균 비율을 구할 수 있습니다.
예를 들어 Cloud Logging 데이터를 쿼리하여 총 jobs.insert
요청 수와 실패한 jobs.insert
요청 수를 가져와 계산을 수행할 수 있습니다. API 대시보드에서 또는 Cloud Monitoring의 측정항목 탐색기를 사용하여 오류율 값을 가져올 수도 있습니다. 이러한 옵션에는 클라이언트와 BigQuery 간에 발생한 네트워킹 또는 라우팅 문제에 관한 데이터가 포함되지 않으므로 더 정확한 실패율 계산을 위해 클라이언트 측 로깅 및 보고 시스템을 사용하는 것이 좋습니다.
먼저 100%에서 전체 요청 실패율을 뺍니다. 이 값이 BigQuery SLA에 설명된 값보다 크거나 같으면 업타임도 BigQuery SLA를 충족합니다. 하지만 이 값이 SLA에 설명된 값보다 작으면 업타임을 수동으로 계산하세요.
업타임을 계산하려면 서비스 다운타임으로 간주되는 분 수를 알아야 합니다. 서비스 다운타임은 SLA 정의에 따라 계산된 오류율이 10%를 초과하는 1분 기간을 의미합니다. 업타임을 계산하려면 지난 30일의 총 시간(분)에서 서비스가 다운된 총 시간(분)을 뺍니다. 남은 시간을 지난 30일의 총 시간(분)으로 나누고 이 값에 100을 곱하여 30일 동안의 업타임 비율을 구합니다. SLA와 관련된 정의 및 계산에 대한 자세한 내용은 BigQuery 서비스수준계약(SLA)을 참고하세요.
월간 업타임 비율이 BigQuery SLA에 설명된 값보다 크거나 같으면 일시적인 문제로 인해 오류가 발생했을 가능성이 높으므로 지수 백오프를 사용하여 계속 다시 시도할 수 있습니다.
업타임이 SLA에 표시된 값보다 낮으면 지원팀에 문의하여 도움을 받고 관찰된 전체 오류율과 업타임 계산을 공유하세요.
인증 오류
OAuth 토큰 생성 시스템에서 발생하는 오류는 OAuth2 사양에 정의된 대로 다음 JSON 객체를 반환합니다.
{"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
을 사용자 또는 서비스 계정의 이메일 주소로 바꿉니다.관리자 활동 감사 로그에서 Identity and Access Management 정책 변경사항 검색:
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: Read timed out | 자바 | 더 큰 시간 제한 값을 설정합니다. |
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) | 자바 | 재시도 메커니즘을 구현하고 제한 시간 값을 더 크게 설정합니다. |
javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake | 자바 | 재시도 메커니즘을 구현하고 제한 시간 값을 더 크게 설정합니다. |
BrokenPipeError: [Errno 32] Broken pipe | Python | 재시도 메커니즘을 구현합니다. 이 오류에 관한 자세한 내용은 BrokenPipeError를 참조하세요. |
Connection aborted. RemoteDisconnected('Remote end closed connection without response' | Python | 더 큰 시간 제한 값을 설정합니다. |
SSLEOFError(프로토콜 위반으로 EOF가 발생함) | Python | 이 오류는 413(ENTITY_TOO_LARGE ) HTTP 오류 대신 반환됩니다. 요청 크기를 줄입니다. |
TaskCanceledException: A task was canceled | .NET 라이브러리 | 클라이언트 측에서 제한 시간 값을 늘립니다. |
google.api_core.exceptions.PreconditionFailed: 412 PATCH | Python | 이 오류는 HTTP 요청을 사용하여 테이블 리소스를 업데이트하려고 할 때 반환됩니다. HTTP 헤더의 ETag가 오래되지 않았는지 확인합니다. 표 또는 데이터 세트 수준 작업의 경우 리소스가 마지막으로 인스턴스화된 이후 변경되지 않았는지 확인하고 필요한 경우 객체를 다시 만듭니다. |
Failed to establish a new connection: [Errno 110] Connection timed out | 클라이언트 라이브러리 | 이 오류는 BigQuery에서 데이터를 스트리밍하거나 읽을 때 이 요청이 파일 끝(EOF)에 도달하면 반환됩니다. 재시도 메커니즘을 구현하고 제한 시간 값을 더 크게 설정합니다. |
socks.ProxyConnectionError: Error connecting to HTTP proxy
|
클라이언트 라이브러리 | 프록시 상태 및 설정 문제를 해결합니다. 재시도 메커니즘을 구현하고 제한 시간 값을 더 크게 설정합니다. |
Received an unexpected EOF or 0 bytes from the transport stream | 클라이언트 라이브러리 | 재시도 메커니즘을 구현하고 제한 시간 값을 더 크게 설정합니다. |
Google Cloud 콘솔 오류 메시지
다음 표에는Google Cloud 콘솔에서 작업하는 동안 표시될 수 있는 오류 메시지가 나열되어 있습니다.
오류 메시지 | 설명 | 문제 해결 |
---|---|---|
서버에서 알 수 없는 오류 응답이 발생했습니다. | 이 오류는 Google Cloud 콘솔에서 서버에서 알 수 없는 오류를 수신한 경우에 표시됩니다. 예를 들어 데이터 세트나 다른 유형의 링크를 클릭하면 페이지가 표시되지 않습니다. | 브라우저의 시크릿 모드 또는 비공개 모드로 전환하고 오류가 발생한 작업을 반복합니다. 시크릿 모드에서 오류가 발생하지 않으면 광고 차단 프로그램과 같은 브라우저 확장 프로그램으로 인한 오류일 수 있습니다. 시크릿 모드가 아닌 상태에서 브라우저 확장 프로그램을 사용 중지하고 문제가 해결되는지 확인합니다. |