apache/beam · error

Unsupported environment

Error message

Unsupported environment %v

What it means

getContainerImage only understands the Docker environment URN (beam:env:docker:v1) or an empty URN. If the pipeline's environment specifies any other URN, the Dataflow runner cannot map it to a container image and panics with the unsupported environment.

Solutions

1. Ensure the pipeline uses the default Docker environment for Dataflow (don't set a custom environment URN)
2. Clear or override the environment URN option before submitting to Dataflow
3. Only submit portable-environment pipelines to runners that support that URN
4. If a custom image is needed, use --sdk_container_image instead of a custom environment URN

Example fix

// before
ctx = beamjobopts.WithEnvironmentUrn(ctx, "beam:env:process:v1")
// after
// omit the custom URN so Dataflow defaults to beam:env:docker:v1

urn := jobopts.GetEnvironmentUrn(ctx)
if urn != "" && urn != "beam:env:docker:v1" {
    return fmt.Errorf("dataflow runner does not support environment %q", urn)
}

func submitToDataflow(ctx context.Context, p *beam.Pipeline) (pr beam.PipelineResult, err error) {
    defer func() { if r := recover(); r != nil { err = fmt.Errorf("unsupported environment: %v", r) } }()
    return dataflow.Execute(ctx, p)
}

When it happens

Trigger: Running a pipeline whose environment URN (from jobopts.GetEnvironmentUrn) is set to something other than "" or "beam:env:docker:v1", e.g. an external/process environment URN carried over from a portable pipeline.

Common situations: Cross-runner pipeline construction where the environment was configured for a portable runner (Flink/Spark URNs) and then submitted to Dataflow, or custom environments set programmatically via jobopts.

Related errors

• A non-standard version of Beam SDK detected
• Dataflow can only execute pipeline steps in Docker…
• environment with urn unimplemented
• unknown environment[ ]
• A cannot be expanded

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

Appendix: source

Thrown at sdks/go/pkg/beam/runners/dataflow/dataflow.go:475

			}
			return *workerHarnessImage
		}
		if *image != "" {
			return *image
		}
		envConfig := jobopts.GetEnvironmentConfig(ctx)
		if envConfig == core.DefaultDockerImage {
			// It's possible the user set the image exactly manually, but unlikely.
			// Prefer using the gcr.io image by default.
			// Note: This doesn't change the dev experience, which requires a user
			// to have a dev image.
			// However, RC versions should automatically be picked up, since
			// they are never tagged the RC number, just the main version.
			return "gcr.io/cloud-dataflow/v1beta3/beam_go_sdk:" + core.SdkVersion
		}
		return envConfig
	}
	panic(fmt.Sprintf("Unsupported environment %v", urn))
}

func checkSoftDeletePolicyEnabled(ctx context.Context, bucketName string, locationName string) {
	bucket, _, err := gcsx.ParseObject(bucketName)
	if err != nil {
		log.Warnf(ctx, "Error parsing bucket name: %v", err)
		return
	}
	client, err := storage.NewClient(ctx)
	if err != nil {
		log.Warnf(ctx, "Error creating GCS client: %v", err)
		return
	}
	defer client.Close()

	if enabled, errMsg := gcsx.SoftDeletePolicyEnabled(ctx, client, bucket); errMsg != nil {
		log.Warnf(ctx, "Error checking SoftDeletePolicy: %v", errMsg)
	} else if enabled {

View on GitHub (pinned to 12126d8942)