{"record":{"id":"16c3fbf0bec5825e","repo":"apache/beam","slug":"schema-update-load-job-failed-with","errorCode":null,"errorMessage":"Schema update load job {} failed with {}","messagePattern":"Schema update load job (.+?) failed with (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/UpdateSchemaDestination.java","lineNumber":324,"sourceCode":"    BigQueryHelpers.PendingJob retryJob =\n        new BigQueryHelpers.PendingJob(\n            // Function to load the data.\n            jobId -> {\n              JobReference jobRef =\n                  new JobReference()\n                      .setProjectId(projectId)\n                      .setJobId(jobId.getJobId())\n                      .setLocation(bqLocation);\n              LOG.info(\n                  \"Loading zero rows using job {}, job id {} iteration {}\",\n                  tableReference,\n                  jobRef,\n                  jobId.getRetryIndex());\n              try {\n                jobService.startLoadJob(\n                    jobRef, loadConfig, new ByteArrayContent(\"text/plain\", new byte[0]));\n              } catch (IOException | InterruptedException e) {\n                LOG.warn(\"Schema update load job {} failed with {}\", jobRef, e.toString());\n                throw new RuntimeException(e);\n              }\n              return null;\n            },\n            // Function to poll the result of a load job.\n            jobId -> {\n              JobReference jobRef =\n                  new JobReference()\n                      .setProjectId(projectId)\n                      .setJobId(jobId.getJobId())\n                      .setLocation(bqLocation);\n              try {\n                return jobService.pollJob(jobRef, BatchLoads.LOAD_JOB_POLL_MAX_RETRIES);\n              } catch (InterruptedException e) {\n                throw new RuntimeException(e);\n              }\n            },\n            // Function to lookup a job.","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/UpdateSchemaDestination.java#L306-L342","documentation":"UpdateSchemaDestination's zero-byte load job (used to apply a schema update without writing rows) failed to start: jobService.startLoadJob threw IOException or InterruptedException. The code logs this warning and rethrows as RuntimeException, so the schema update step (and the write relying on it) fails.","triggerScenarios":"startLoadJob(jobRef, loadConfig, emptyContent) throws — invalid job configuration, quota exceeded, permission denied for jobs.insert, or interruption while submitting.","commonSituations":"Service account missing bigquery.jobs.create; too many load jobs in flight (quota); schema in loadConfig invalid for the table (e.g. incompatible field type change); transient Google API outage.","solutions":["Read e.toString(): if 403, grant roles/bigquery.jobUser and roles/bigquery.dataEditor to the service account.","If quota/rate errors, reduce parallel write destinations or request higher BigQuery load-job quota.","Verify the new schema is compatible with existing table data (no required-field narrowing, no unsupported type changes).","Retry on transient errors; check BigQuery job history for the failed jobRef for server-side details."],"exampleFix":"// before: schema update fails with 403\n// grant job submission rights\ngcloud projects add-iam-policy-binding proj --member=serviceAccount:sa@proj.iam.gserviceaccount.com --role=roles/bigquery.jobUser\n// after: startLoadJob succeeds","handlingStrategy":"retry","validationCode":"// pre-flight: ensure the service account can insert load jobs\nbq.create(JobInfo.of(LoadJobConfiguration.of(tableId, \"gs://nonexistent-probe\"))); // expect quota/permission errors early","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Grant roles/bigquery.jobUser to the runner service account.","Validate the new schema is compatible with existing table data.","Stay within load-job quotas (reduce parallel destinations if needed)."],"tags":["bigquery","load-job","api","permissions"],"backgroundTag":"api-error-response","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}