experiment worker_region and option workerZone are mutually…

Error message

experiment worker_region and option workerZone are mutually exclusive

What it means

validateWorkerSettings rejects a job that enables the worker_region experiment while also setting the workerZone option. Zonal placement via workerZone conflicts with declaring a worker region through the experiments mechanism.

Solutions

Remove the worker_region experiment and keep --worker_zone for zonal placement.
Or, if regional placement is intended, drop --worker_zone and use the --worker_region option instead of the experiment.
Decide regional vs zonal placement once and set only one mechanism.

Example fix

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

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.WorkerZone != "" {
    // zonal requested: strip the regional experiment
    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 workerZone") {
    // remove the experiment and retry with worker_zone
}

Prevention

Decide regional vs zonal placement before building JobOptions.
Never combine the worker_region experiment with zone-based options.
Strip worker_region experiments when migrating to worker_zone.

When it happens

Trigger: JobOptions.Experiments contains a string with prefix "worker_region" AND opts.WorkerZone != "" during Translate.

Common situations: Launcher adds --experiment=worker_region=... while the job also specifies --worker_zone=us-central1-a; mixed legacy/new flag sets in the same pipeline config.

Related errors

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

Appendix: source

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

		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)
	}
	if maxNumWorkers < 0 {
		return fmt.Errorf("max_num_workers (%d) cannot be negative", maxNumWorkers)

View on GitHub (pinned to 12126d8942)