{"record":{"id":"eb568af125630dd2","repo":"apache/beam","slug":"job-failed-to-prepare","errorCode":null,"errorMessage":"job failed to prepare","messagePattern":"job failed to prepare","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/runners/universal/runnerlib/job.go","lineNumber":79,"sourceCode":"\t\tOptions:      beam.PipelineOptions.Export(),\n\t\tAppName:      opt.Name,\n\t\tExperiments:  append(opt.Experiments, \"beam_fn_api\"),\n\t\tRetainDocker: opt.RetainDocker,\n\t\tParallelism:  opt.Parallelism,\n\t}\n\n\toptions, err := tools.OptionsToProto(raw)\n\tif err != nil {\n\t\treturn \"\", \"\", \"\", errors.WithContext(err, \"producing pipeline options\")\n\t}\n\treq := &jobpb.PrepareJobRequest{\n\t\tPipeline:        p,\n\t\tPipelineOptions: options,\n\t\tJobName:         opt.Name,\n\t}\n\tresp, err := client.Prepare(ctx, req)\n\tif err != nil {\n\t\treturn \"\", \"\", \"\", errors.Wrap(err, \"job failed to prepare\")\n\t}\n\treturn resp.GetPreparationId(), resp.GetArtifactStagingEndpoint().GetUrl(), resp.GetStagingSessionToken(), nil\n}\n\n// Submit submits a job to the given job service. It returns a jobID, if successful.\nfunc Submit(ctx context.Context, client jobpb.JobServiceClient, id, token string) (string, error) {\n\treq := &jobpb.RunJobRequest{\n\t\tPreparationId:  id,\n\t\tRetrievalToken: token,\n\t}\n\n\tresp, err := client.Run(ctx, req)\n\tif err != nil {\n\t\treturn \"\", errors.Wrap(err, \"failed to submit job\")\n\t}\n\treturn resp.GetJobId(), nil\n}\n","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/runners/universal/runnerlib/job.go#L61-L97","documentation":"Before submitting a job to a universal (remote) runner, Prepare calls the JobService's Prepare RPC with the pipeline, options, and job name. Any failure of this RPC is wrapped as \"job failed to prepare\". Preparation is the first stage of job submission, so this usually means the runner cannot accept the job at all.","triggerScenarios":"client.Prepare(ctx, req) returns an error — connection failure, auth rejection, malformed pipeline options, or server-side validation failure — when called from Execute.","commonSituations":"Wrong or unreachable runner endpoint (--endpoint); runner service down; TLS/auth misconfiguration; unsupported pipeline options; stale runner version that rejects the submitted pipeline proto.","solutions":["Check the wrapped gRPC error: if it's a connection error, verify the --endpoint host:port and that the runner service is up.","Verify auth/TLS settings between client and runner.","Confirm pipeline options are valid and supported by the runner version.","Retry once transient network issues are ruled out."],"exampleFix":"// before\nbeam.Run(ctx, universal.New(ctx, \"bad-host:8099\"), p)\n// after\nbeam.Run(ctx, universal.New(ctx, \"runner.example.com:8099\"), p)","handlingStrategy":"validation","validationCode":"// Go: verify the runner endpoint is reachable before submission\nconn, err := grpc.Dial(endpoint, grpc.WithTransportCredentials(creds))\nif err != nil { return fmt.Errorf(\"runner endpoint %s unreachable: %w\", endpoint, err) }","typeGuard":null,"tryCatchPattern":"if err := beam.Run(ctx, runner, p); err != nil && strings.Contains(err.Error(), \"job failed to prepare\") {\n    // check endpoint, TLS, auth, and runner health before retrying\n}","preventionTips":["Verify the --endpoint host:port is correct and the runner service is up.","Test connectivity (telnet/nc) to the runner before submitting jobs.","Match client SDK and runner versions.","Confirm pipeline options are accepted by the target runner."],"tags":["go","beam","grpc","job-submission"],"backgroundTag":"connection-refused","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}