apache/beam · critical

tried cross-language for %v against %v and failed

Error message

tried cross-language for %v against %v and failed

What it means

beam.CrossLanguage submits a cross-language transform to an expansion service and, unlike TryCrossLanguage, treats any expansion failure as fatal by panicking with context about the URN and expansion address. The panic wraps the underlying error (typically from the expansion service request) via errors.WithContextf, so the root cause is preserved in the message.

Source

Thrown at sdks/go/pkg/beam/xlang.go:165

// CrossLanguage call.
//
// In addition, urns can be bound to specific expansion addresses, using
// xlangx.RegisterOverrideForUrn. This allows for testing specific overrides, or other
// custom implementations to be used instead.
//
// To ignore overrides regardless of URN, wrapping the expansion address in
// a call to xlangx.Require, will force expansion using the given address.
func CrossLanguage(
	s Scope,
	urn string,
	payload []byte,
	expansionAddr string,
	namedInputs map[string]PCollection,
	namedOutputTypes map[string]FullType,
) map[string]PCollection {
	namedOutputs, err := TryCrossLanguage(s, urn, payload, expansionAddr, namedInputs, namedOutputTypes)
	if err != nil {
		panic(errors.WithContextf(err, "tried cross-language for %v against %v and failed", urn, expansionAddr))
	}
	return namedOutputs
}

// TryCrossLanguage coordinates the core functions required to execute the cross-language transform.
// See CrossLanguage for user documentation.
func TryCrossLanguage(
	s Scope,
	urn string,
	payload []byte,
	expansionAddr string,
	namedInputs map[string]PCollection,
	namedOutputTypes map[string]FullType,
) (map[string]PCollection, error) {
	if !s.IsValid() {
		panic(errors.New("invalid scope"))
	}

View on GitHub (pinned to 12126d8942)

Solutions

1. Read the wrapped cause in the panic message — it names the actual expansion failure (connection refused, unknown URN, etc.).
2. Verify the expansion service is running and expansionAddr (host:port) is correct and reachable.
3. Switch to beam.TryCrossLanguage to handle the error gracefully and return it to callers.
4. Confirm the transform URN and payload match the version of the expansion service you are connecting to.
5. Check network/namespace connectivity (e.g. k8s service DNS, Docker port mapping) between the pipeline and the service.

Example fix

// before
beam.CrossLanguage(s, urn, payload, "localhost:32768", inputs, outputs) // panics on any expansion error
// after
outs, err := beam.TryCrossLanguage(s, urn, payload, "localhost:32768", inputs, outputs)
if err != nil {
    return fmt.Errorf("expanding %s via localhost:32768: %w", urn, err)
}

// verify the expansion service before building the pipeline
conn, err := net.DialTimeout("tcp", expansionAddr, 5*time.Second)
if err != nil {
    return fmt.Errorf("expansion service %s unreachable: %w", expansionAddr, err)
}
conn.Close()

// prefer TryCrossLanguage over the panicking CrossLanguage:
outs, err := beam.TryCrossLanguage(s, urn, payload, expansionAddr, inputs, outputs)
if err != nil {
    return fmt.Errorf("cross-language %s via %s failed: %w", urn, expansionAddr, err)
}

When it happens

Trigger: Calling beam.CrossLanguage (directly or via Prefix, CoGroupByKey, CombinePerKey, CombineGlobally, Flatten, GroupByKey helpers) where TryCrossLanguage returns an error: expansion service unreachable at expansionAddr, unknown transform URN, malformed payload, or the external transform failing schema validation on the service side.

Common situations: Wrong or stale expansion service address/port; expansion service container not started (e.g. Kafka/SQL expansion service); URN or payload mismatch after upgrading the external transform's jar/module; network/firewall blocking the expansion endpoint.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• res.GetError()
• mismatched number of named outputs: received - %v expected -
• Could not find coder for URN " + urn
• type annotation for multiple outputs is not allowed yet: %s
• invalid scope

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