이 표에는 모든 가능한 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
이 오류는 액세스할 권한이 없는 데이터 세트, 테이블, 뷰, 작업과 같은 리소스에 액세스하려고 하면 반환됩니다. 읽기 전용 객체를 수정하려 하는 경우에도 이 오류가 반환됩니다.
리소스 소유자에게 연락하여 오류의 감사 로그에서 principalEmail 값으로 식별된 사용자에 대해 리소스에 대한 액세스를 요청하세요.
backendError
500 또는 503
이 오류는 네트워크 연결 문제 또는 서버 과부하와 같은 일시적인 서버 장애 발생 시 반환됩니다.
일반적으로 몇 초 정도 기다린 후 다시 시도합니다. 문제가 반복되면 지수 백오프로 다시 시도합니다.
그러나 이 오류의 문제 해결을 위한 두 가지 특수한 사례(jobs.get 호출과 jobs.insert 호출)가 있습니다.
jobs.get 호출
jobs.get 폴링 시 503 오류가 발생하면 몇 초 정도 기다린 후 다시 폴링합니다.
작업이 완료되더라도 backendError가 있는 오류 객체가 포함되면 작업은 실패합니다. 데이터 일관성에 대해 걱정할 필요 없이 안전하게 작업을 재시도할 수 있습니다.
jobs.insert 호출
jobs.insert 호출 시 이 오류가 발생하면 작업 성공 여부가 분명하지 않습니다. 이 경우 작업을 재시도해야 합니다.
badRequest
400
테이블에서 최근에 스트리밍된 일부 행을 일반적으로 몇 분 동안, 드물게는 최대 90분 동안 DML 작업(DELETE, UPDATE, MERGE)에서 사용할 수 없는 경우 'UPDATE or DELETE statement over table <project.dataset.table> would
affect rows in the streaming buffer, which is not supported' 오류가 발생할 수 있습니다. 자세한 내용은 스트리밍 데이터 가용성 및 DML 제한사항을 참조하세요.
테이블 DML 작업에 데이터를 사용할 수 있는지 확인하려면 streamingBuffer 섹션의 tables.get 응답을 확인하세요. streamingBuffer 섹션이 없으면 DML 작업에 테이블 데이터를 사용할 수 있는 것입니다. streamingBuffer.oldestEntryTime 필드를 사용하여 스트리밍 버퍼의 레코드 기간을 식별할 수도 있습니다.
이 오류는 주문형 작업의 statistics.query.billingTier 값이 100을 초과하면 반환됩니다. 이 오류는 주문형 쿼리가 스캔되는 데이터의 양에 비해 너무 많은 CPU를 사용하는 경우에 발생합니다. 작업 세부정보를 검사하는 방법에 대한 안내는 작업 관리를 참고하세요.
이 오류는 예를 들어 부정확한 조인 조건으로 인해 명시적으로 또는 암시적으로 비효율적인 교차 조인을 실행하는 경우에 가장 자주 발생합니다. 이러한 유형의 쿼리는 리소스 소비가 많아서 주문형 가격 책정에 적합하지 않으며 일반적으로 확장에 적합하지 않을 수 있습니다. 쿼리를 최적화하거나 용량 기반(슬롯) 가격 책정 모델을 사용하도록 전환하여 이 오류를 해결할 수 있습니다. 쿼리 최적화에 대한 자세한 내용은 SQL 안티패턴 방지를 참조하세요.
차단됨
403
이 오류는 일반적으로 서비스 중단을 방지하기 위해 BigQuery에서 사용자가 시도하는 작업을 일시적으로 차단 목록에 포함하는 경우에 반환됩니다.
이 오류는 존재하지 않는 리소스(데이터 세트, 테이블 또는 작업)를 참조하거나 요청의 위치가 리소스 위치(예: 작업이 실행되는 위치)와 일치하지 않으면 반환됩니다.
테이블 데코레이터를 사용하여 최근에 스트리밍되었지만 삭제된 테이블을 참조하는 경우에도 이 오류가 발생할 수 있습니다.
리소스 이름을 수정하거나 위치를 올바르게 지정하거나 삭제된 테이블을 쿼리하기 전에 스트리밍 후 최소 6시간을 기다립니다.
이 오류는 요청에 프록시 서버에 대한 유효한 인증 사용자 인증 정보가 없을 때 클라이언트 환경과 프록시 서버 간에 반환됩니다. 자세한 내용은 407 프록시 인증 필요를 참고하세요.
문제 해결은 환경에 따라 다릅니다. Java에서 작업하는 동안 이 오류가 발생하면 등호 뒤에 값이 없는 jdk.http.auth.tunneling.disabledSchemes= 및 jdk.http.auth.proxying.disabledSchemes= 속성을 모두 설정했는지 확인하세요.
초과된 할당량에 대한 자세한 내용은 오류 객체의 message 속성을 참조하세요. BigQuery 할당량을 재설정하거나 늘리려면 지원팀에 문의합니다.
커스텀 할당량을 수정하려면 Google Cloud 콘솔 페이지에서 요청을 제출하세요. BigQuery 샌드박스를 사용하다가 이 오류가 발생하면 샌드박스에서 업그레이드하면 됩니다.
이 오류는 테이블이 포함된 데이터 세트를 삭제하려 하거나 현재 실행 중인 작업을 삭제하려 하는 경우에 반환됩니다.
데이터세트를 삭제하기 전에 비우거나 작업이 완료될 때까지 기다린 후에 데이터세트를 삭제합니다.
resourcesExceeded
400
이 오류는 작업에서 과다한 리소스를 사용하는 경우 반환됩니다.
이 오류는 작업에서 과다한 리소스를 사용하는 경우 반환됩니다. 문제 해결 정보는 리소스 초과 오류 문제 해결을 참고하세요.
responseTooLarge
403
이 오류는 쿼리 결과가 최대 응답 크기보다 큰 경우에 반환됩니다. 일부 쿼리는 여러 단계로 실행되며, 어느 단계에서 지나치게 큰 응답 크기를 반환하면 최종 결과가 최댓값보다 작더라도 이 오류가 반환됩니다. 이 오류는 쿼리에서 ORDER BY 절을 사용하는 경우에 흔히 반환됩니다.
LIMIT 절을 추가하거나 ORDER BY 절을 삭제하면 도움이 될 수 있습니다. 크기가 큰 결과가 반환되도록 하려면 allowLargeResults 속성을 true로 설정하고 대상 테이블을 지정하면 됩니다. 자세한 내용은 큰 쿼리 결과 쓰기를 참조하세요.
중지됨
200
이 상태 코드는 작업이 취소되는 경우 반환됩니다.
tableUnavailable
400
특정 BigQuery 테이블에는 다른 Google 제품팀이 관리하는 데이터가 사용됩니다. 이 오류는 이러한 테이블 중 하나를 사용할 수 없음을 나타냅니다.
이 오류 메시지가 표시되면 요청을 다시 시도하거나(internalError 문제 해결 제안 참조) 데이터 액세스 권한을 부여한 Google 제품팀에 문의합니다.
timeout
400
작업 시간이 초과되었습니다.
설정된 한도 내에서 연산을 완료할 수 있도록 연산에서 수행하는 작업량을 줄이는 것이 좋습니다. 할당량 및 한도를 참조하세요.
다음 표에는 클라이언트 라이브러리를 사용하거나 코드에서 BigQuery API를 호출할 때 간헐적인 연결 문제로 인해 표시될 수 있는 오류 메시지 목록이 나와 있습니다.
오류 메시지
클라이언트 라이브러리 또는 API
문제 해결
com.google.cloud.bigquery.BigQueryException: 읽기 시간 초과
Java
더 큰 시간 제한 값을 설정합니다.
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
재시도 메커니즘을 구현하고 제한 시간 값을 더 크게 설정합니다.
javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake
이 오류는 HTTP 요청을 사용하여 테이블 리소스를 업데이트하려고 할 때 반환됩니다. HTTP 헤더의 ETag가 오래되지 않았는지 확인합니다. 테이블 또는 데이터 세트 수준 작업의 경우 리소스가 마지막으로 인스턴스화된 이후 변경되지 않았는지 확인하고 필요한 경우 객체를 다시 만듭니다.
Google Cloud 콘솔 오류 메시지
다음 표에는 Google Cloud 콘솔에서 작업하는 동안 표시될 수 있는 오류 메시지가 나열되어 있습니다.
오류 메시지
설명
문제 해결
서버에서 알 수 없는 오류 응답이 발생했습니다.
이 오류는 Google Cloud 콘솔에서 서버에서 알 수 없는 오류를 수신한 경우에 표시됩니다. 예를 들어 데이터 세트나 다른 유형의 링크를 클릭하면 페이지가 표시되지 않습니다.
브라우저의 시크릿 모드 또는 비공개 모드로 전환하고 오류가 발생한 작업을 반복합니다. 시크릿 모드에서 오류가 발생하지 않으면 광고 차단 프로그램과 같은 브라우저 확장 프로그램으로 인한 오류일 수 있습니다. 시크릿 모드가 아닌 상태에서 브라우저 확장 프로그램을 사용 중지하고 문제가 해결되는지 확인합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-02-19(UTC)"],[[["\u003cp\u003eThis document provides a comprehensive guide to understanding and troubleshooting error messages encountered when using BigQuery, including HTTP error codes and specific error objects.\u003c/p\u003e\n"],["\u003cp\u003eBigQuery API responses may include \u003ccode\u003eerrors\u003c/code\u003e or \u003ccode\u003eerrorResults\u003c/code\u003e objects with \u003ccode\u003eErrorProto\u003c/code\u003e details, and the \u003ccode\u003ereason\u003c/code\u003e property within these objects corresponds to the "Error message" in the provided error table.\u003c/p\u003e\n"],["\u003cp\u003eHTTP response codes in the \u003ccode\u003e5xx\u003c/code\u003e range indicate server-side issues, suggesting users retry requests later and examine the response body for error details.\u003c/p\u003e\n"],["\u003cp\u003eAuthentication errors, detailed by OAuth2 specifications, can be reviewed using the logs explorer, with specific filters available for identifying policy denials, user authentication issues, and IAM policy changes.\u003c/p\u003e\n"],["\u003cp\u003eConnectivity errors encountered with client libraries or the API, often related to timeouts or broken pipes, generally suggest implementing retry mechanisms and adjusting timeout values.\u003c/p\u003e\n"]]],[],null,["# Error messages\n==============\n\nThis document describes error messages that you might encounter when working with\nBigQuery, including HTTP error codes and suggested troubleshooting\nsteps.\n\nFor more information about query errors, see\n[Troubleshoot query errors](/bigquery/docs/troubleshoot-queries).\n\nFor more information about streaming insert errors, see\n[Troubleshoot streaming inserts](/bigquery/docs/streaming-data-into-bigquery#troubleshooting).\n\nError table\n-----------\n\nResponses from the BigQuery API include an HTTP error code and an error object\nin the response body. An error object is typically one of the following:\n\n- An [`errors` object](/bigquery/docs/reference/rest/v2/Job#jobstatus), which contains an array of [`ErrorProto`\n objects](/bigquery/docs/reference/rest/v2/tables#errorproto).\n- An [`errorResults` object](/bigquery/docs/reference/rest/v2/Job#jobstatus), which contains a single [`ErrorProto`\n object](/bigquery/docs/reference/rest/v2/tables#errorproto).\n\nThe **Error message** column in the following table maps to the `reason` property\nin an `ErrorProto` object.\n\nThe table does not include all possible HTTP errors or other networking errors.\nTherefore, don't assume that an error object is present in every error response\nfrom BigQuery. In addition, you might receive different errors or\nerror objects if you use the Cloud Client Libraries for the BigQuery API. For\nmore information, see [BigQuery API Client\nLibraries](/bigquery/docs/reference/libraries).\n\nIf you receive an HTTP response code that doesn't appear in the following table,\nthe response code indicates an issue or an expected result with the HTTP\nrequest. Response codes in the `5xx` range indicate a server-side error. If you\nreceive a `5xx` response code, then retry the request later. In some cases, a\n`5xx` response code might be returned by an intermediate server such as a\nproxy. Examine the response body and response headers for details about the\nerror. For a full list of HTTP response codes, see [HTTP response\ncodes](https://en.wikipedia.org/wiki/HTTP_response_codes).\n\nIf you use the [bq command-line tool](/bigquery/bq-command-line-tool) to check job status,\nthe error object is not returned by default. To view the error object and the\ncorresponding `reason` property that maps to the following table, use the\n`--format=prettyjson` flag. For example, `bq --format=prettyjson show -j\n*\u003cjob id\u003e*`. To view verbose logging for the bq tool, use\n`--apilog=stdout`. To learn more about troubleshooting the bq tool,\nsee [Debugging](/bigquery/docs/bq-command-line-tool#debugging).\n\n### Sample error response\n\n GET https://bigquery.googleapis.com/bigquery/v2/projects/12345/datasets/foo\n Response:\n [404]\n {\n \"error\": {\n \"errors\": [\n {\n \"domain\": \"global\",\n \"reason\": \"notFound\",\n \"message\": \"Not Found: Dataset myproject:foo\"\n }],\n \"code\": 404,\n \"message\": \"Not Found: Dataset myproject:foo\"\n }\n }\n\n### Calculate rate of failing requests and uptime\n\nThe majority of 500 and 503 errors can be resolved by performing a retry with\nexponential backoff. In the case where 500 and 503 errors still persist, you\ncan calculate the overall rate of failing requests and corresponding uptime to\ncompare it to the [BigQuery Service Level Agreement\n(SLA)](/bigquery/sla) to determine if the service is working as expected.\n\nTo calculate the overall rate of failing requests during the last 30 days, take\nthe number of failed requests for a specific API call or method from the last\n30 days and divide by the total number of requests for that API call or method\nfrom the last 30 days. Multiply this value by 100 to get the average percentage\nof failed requests over 30 days.\n\nFor example, you can query [Cloud Logging\ndata](/logging/docs/view/logging-query-language) to get the number of total\n`jobs.insert` requests and the number of failed `jobs.insert` requests and\nperform the calculation. You can also obtain the error rate values from the\n[API dashboard](/apis/docs/monitoring#using_the_api_dashboard) or using the\nMetrics Explorer in [Cloud Monitoring](/apis/docs/monitoring#using). These\noptions won't include data about networking or routing problems encountered\nbetween the client and BigQuery, so we also recommend using a\nclient-side logging and reporting system for more precise failure rate\ncalculations.\n\nFirst, take 100% minus the overall rate of failing requests. If this value is\nmore than or equal to the value described in the BigQuery SLA,\nthen the uptime also meets the BigQuery SLA. However, if this\nvalue is less than the value described in the SLA, calculate the uptime\nmanually.\n\nIn order to calculate the uptime, you need to know the number of minutes that\nare considered service downtime. Service downtime means a period of one minute\nwith more than 10% error rate calculated according to SLA definitions. To\ncalculate the uptime, take the total minutes from the last 30 days and subtract\nthe total minutes that the service was down. Divide the remaining time by the\ntotal minutes from the last 30 days and multiply this value by 100 to get the\npercentage of uptime over 30 days. For more information about the definitions\nand calculations related to SLA , see [BigQuery Service Level\nAgreement (SLA)](/bigquery/sla)\n\nIf your monthly uptime percentage is greater than or equal to the value\ndescribed in the BigQuery SLA, then the error was most likely\ncaused by a transient issue, so you can continue to retry using [exponential\nbackoff](/monitoring/api/troubleshooting#exponential-retry).\n\nIf the uptime is below the value presented in the SLA, [contact\nsupport](/support) for help and share the observed overall error rate and\nuptime calculations.\n\nAuthentication errors\n---------------------\n\nErrors thrown by the OAuth token generation system return the following JSON\nobject, as defined by the [OAuth2\nspecification](https://tools.ietf.org/html/rfc6749#section-5.2).\n\n`{\"error\" : \"_description_string_\"}`\n\nThe error is accompanied by either an HTTP `400` Bad Request error or an HTTP\n`401` Unauthorized error. `_description_string_` is one of the error codes\ndefined by the OAuth2 specification. For example:\n\n`{\"error\":\"invalid_client\"}`\n\n### Review errors\n\nYou can use the [logs explorer](/logging/docs/view/logs-explorer-interface) to\nview authentication errors for specific jobs, users, or other scopes. The\nfollowing are examples of logs explorer filters that you can use to review\nauthentication errors:\n\n- Search for failed jobs with permission issues in the Policy Denied audit\n logs:\n\n resource.type=\"bigquery_resource\"\n protoPayload.status.message=~\"Access Denied\"\n logName=\"projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/logs/cloudaudit.googleapis.com%2Fdata_access\"\n\n Replace \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e with the ID of the project\n containing the resource.\n- Search for a specific user or service account used for authentication:\n\n resource.type=\"bigquery_resource\"\n protoPayload.authenticationInfo.principalEmail=\"\u003cvar translate=\"no\"\u003eEMAIL\u003c/var\u003e\"\n\n Replace \u003cvar translate=\"no\"\u003eEMAIL\u003c/var\u003e with the email address of the user or\n service account.\n- Search for Identity and Access Management policy changes in the Admin Activity audit\n logs:\n\n protoPayload.methodName=~\"SetIamPolicy\"\n logName=\"projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/logs/cloudaudit.googleapis.com%2Factivity\"\n\n- Search for changes to a specific BigQuery dataset in the\n Data Access audit logs:\n\n resource.type=\"bigquery_resource\"\n protoPayload.resourceName=\"projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/datasets/\u003cvar translate=\"no\"\u003eDATASET_ID\u003c/var\u003e\"\n logName=projects/\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-n\"\u003ePROJECT_ID\u003c/span\u003e\u003c/var\u003e/logs/cloudaudit.googleapis.com%2Fdata_access\n\n Replace \u003cvar translate=\"no\"\u003eDATASET_ID\u003c/var\u003e with the ID of the dataset containing the resource.\n\nConnectivity error messages\n---------------------------\n\nThe following table lists error messages that you might see because of\nintermittent connectivity issues when using the client libraries or calling the\nBigQuery API from your code:\n\nGoogle Cloud console error messages\n-----------------------------------\n\nThe following table lists error messages that you might see while you work in the\nGoogle Cloud console."]]
