experiment worker_region and option workerRegion are…

Error message

experiment worker_region and option workerRegion are mutually exclusive

What it means

validateWorkerSettings rejects a job that enables the worker_region experiment (an --experiment=worker_region=... flag) while also setting the workerRegion option. The same setting is expressed twice via different mechanisms, which the library treats as conflicting.

Solutions

Remove the worker_region experiment from --experiments and set only the --worker_region option (preferred modern form).
Or remove the --worker_region option and keep only the experiment if targeting an older setup.
Dedupe experiments lists so the same placement is not declared twice.

Example fix

// before
// --experiment=worker_region=us-central1 --worker_region=us-central1
// after
// --worker_region=us-central1

Defensive patterns

Strategy: validation

Validate before calling

hasExp := false
for _, e := range opts.Experiments {
    if strings.HasPrefix(e, "worker_region") { hasExp = true }
}
if hasExp && opts.WorkerRegion != "" {
    // drop the experiment; the option form is preferred
    filtered := opts.Experiments[:0]
    for _, e := range opts.Experiments { if !strings.HasPrefix(e, "worker_region") { filtered = append(filtered, e) } }
    opts.Experiments = filtered
}

Try / catch

if err := dataflowlib.ValidateWorkerSettings(ctx, opts); err != nil && strings.Contains(err.Error(), "experiment worker_region and option workerRegion") {
    // remove the experiment flag and retry with the option form
}

Prevention

Use the --worker_region option, never the worker_region experiment, in new pipelines.
Dedupe experiments lists after merging defaults and user flags.
Review pipeline templates for legacy --experiment=worker_region=... entries.

When it happens

Trigger: JobOptions.Experiments contains a string with prefix "worker_region" (e.g. "worker_region=us-central1") AND opts.WorkerRegion != "" during Translate.

Common situations: Pipeline code adding the experiment programmatically while the launcher also passes --worker_region; template defaults carrying the experiment flag plus new-style options.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/4b73b91ea1d0f846. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/runners/dataflow/dataflowlib/job.go:421

		return errors.New("cannot use option zone with workerRegion; prefer either workerZone or workerRegion")
	}
	if opts.Zone != "" && opts.WorkerZone != "" {
		return errors.New("cannot use option zone with workerZone; prefer workerZone")
	}
	if opts.WorkerZone != "" && opts.WorkerRegion != "" {
		return errors.New("workerRegion and workerZone options are mutually exclusive")
	}

	hasExperimentWorkerRegion := false
	for _, experiment := range opts.Experiments {
		if strings.HasPrefix(experiment, "worker_region") {
			hasExperimentWorkerRegion = true
			break
		}
	}

	if hasExperimentWorkerRegion && opts.WorkerRegion != "" {
		return errors.New("experiment worker_region and option workerRegion are mutually exclusive")
	}
	if hasExperimentWorkerRegion && opts.WorkerZone != "" {
		return errors.New("experiment worker_region and option workerZone are mutually exclusive")
	}
	if hasExperimentWorkerRegion && opts.Zone != "" {
		return errors.New("experiment worker_region and option Zone are mutually exclusive")
	}

	if opts.Zone != "" {
		log.Warn(ctx, "Option --zone is deprecated. Please use --workerZone instead.")
		opts.WorkerZone = opts.Zone
		opts.Zone = ""
	}

	numWorkers := opts.NumWorkers
	maxNumWorkers := opts.MaxNumWorkers
	if numWorkers < 0 {
		return fmt.Errorf("num_workers (%d) cannot be negative", numWorkers)

View on GitHub (pinned to 12126d8942)