{"record":{"id":"4958e3be16d48071","repo":"apache/beam","slug":"cannot-use-option-zone-with-workerregion-prefer-either","errorCode":null,"errorMessage":"cannot use option zone with workerRegion; prefer either workerZone or workerRegion","messagePattern":"cannot use option zone with workerRegion; prefer either workerZone or workerRegion","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go","lineNumber":403,"sourceCode":"\taddIfNonEmpty(\"region\", opts.Region)\n\taddIfNonEmpty(\"zone\", opts.Zone)\n\taddIfNonEmpty(\"worker_region\", opts.WorkerRegion)\n\taddIfNonEmpty(\"worker_zone\", opts.WorkerZone)\n\taddIfNonEmpty(\"network\", opts.Network)\n\taddIfNonEmpty(\"subnetwork\", opts.Subnetwork)\n\taddIfNonEmpty(\"machine_type\", opts.MachineType)\n\taddIfNonEmpty(\"container_images\", strings.Join(images, \",\"))\n\taddIfNonEmpty(\"temp_location\", opts.TempLocation)\n\n\tfor k, v := range opts.Options.Options {\n\t\tret = append(ret, newDisplayData(k, \"\", \"go_options\", v))\n\t}\n\treturn ret\n}\n\nfunc validateWorkerSettings(ctx context.Context, opts *JobOptions) error {\n\tif opts.Zone != \"\" && opts.WorkerRegion != \"\" {\n\t\treturn errors.New(\"cannot use option zone with workerRegion; prefer either workerZone or workerRegion\")\n\t}\n\tif opts.Zone != \"\" && opts.WorkerZone != \"\" {\n\t\treturn errors.New(\"cannot use option zone with workerZone; prefer workerZone\")\n\t}\n\tif opts.WorkerZone != \"\" && opts.WorkerRegion != \"\" {\n\t\treturn errors.New(\"workerRegion and workerZone options are mutually exclusive\")\n\t}\n\n\thasExperimentWorkerRegion := false\n\tfor _, experiment := range opts.Experiments {\n\t\tif strings.HasPrefix(experiment, \"worker_region\") {\n\t\t\thasExperimentWorkerRegion = true\n\t\t\tbreak\n\t\t}\n\t}\n\n\tif hasExperimentWorkerRegion && opts.WorkerRegion != \"\" {\n\t\treturn errors.New(\"experiment worker_region and option workerRegion are mutually exclusive\")","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go#L385-L421","documentation":"validateWorkerSettings rejects a Dataflow job configuration that sets both the legacy --zone option and the newer workerRegion option, since the pipeline cannot be pinned to both a specific zone and a whole region. The error tells the user to migrate to workerZone (zonal) or keep workerRegion (regional).","triggerScenarios":"JobOptions with Zone != \"\" AND WorkerRegion != \"\"; e.g. passing --zone=us-central1-a plus --worker_region=us-central1, or programmatically setting both fields on dataflow.JobOptions before Translate.","commonSituations":"Legacy scripts still passing --zone after the team added --worker_region for regional endpoints; mixing old and new pipeline options when upgrading Beam versions.","solutions":["Remove --zone and keep --worker_region (regional placement).","Replace --zone with --worker_zone=us-central1-a if zonal placement is required.","If zone is set only by stale code/config, unset it before building JobOptions."],"exampleFix":"// before\n// --zone=us-central1-a --worker_region=us-central1\n// after\n// --worker_region=us-central1        (regional)\n// or: --worker_zone=us-central1-a   (zonal)","handlingStrategy":"validation","validationCode":"if opts.Zone != \"\" && opts.WorkerRegion != \"\" {\n    opts.WorkerZone = opts.Zone; opts.Zone = \"\" // normalize to worker_zone\n}","typeGuard":null,"tryCatchPattern":"if err := dataflowlib.ValidateWorkerSettings(ctx, opts); err != nil && strings.Contains(err.Error(), \"option zone with workerRegion\") {\n    // strip legacy zone and retry translation\n}","preventionTips":["Ban the legacy --zone flag in launch scripts and CI.","Standardize on --worker_region or --worker_zone exclusively.","Sanitize/merge option sets centrally before constructing JobOptions."],"tags":["dataflow","gcp","configuration","flags"],"backgroundTag":"mutually-exclusive-options","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"}