lpUnknownCoders: couldn't handle component %d %q of %q %v: %

Error message

lpUnknownCoders: couldn't handle component %d %q of %q %v:
%w

What it means

When lpUnknownCoders recursively processes a composite coder's components, a failure on any child coder is wrapped with its index, ID, and prototext form. This error means a component coder within a composite could not be resolved or length-prefixed, propagating the root cause up the coder tree.

Source

Thrown at sdks/go/pkg/beam/runners/prism/internal/coders.go:183

	}
	// If it is a leaf, move its components (if any) to the coders map.
	if leaf {
		// Copy the components from the base.
		for _, cc := range c.GetComponentCoderIds() {
			bundle[cc] = base[cc]
		}
		return cID, nil
	}

	// Now we have a known composite.
	// We may need to LP its components. If so, we make a new composite with the
	// LP'd components.
	var needNewComposite bool
	var comps []string
	for i, cc := range c.GetComponentCoderIds() {
		rcc, err := lpUnknownCoders(cc, bundle, base)
		if err != nil {
			return "", fmt.Errorf("lpUnknownCoders: couldn't handle component %d %q of %q %v:\n%w", i, cc, cID, prototext.Format(c), err)
		}
		if cc != rcc {
			needNewComposite = true
		}
		comps = append(comps, rcc)
	}
	if needNewComposite {
		lpc := &pipepb.Coder{
			Spec:              c.GetSpec(),
			ComponentCoderIds: comps,
		}
		bundle[lpcID] = lpc
		return lpcID, nil
	}
	return cID, nil
}

// forceLpCoder always add a new LP-coder for a given coder into the "base" map

View on GitHub (pinned to 12126d8942)

Solutions

Follow the wrapped error chain to the leaf coder that is missing and ensure it is registered in the pipeline coders map
Re-run/inspect the expansion service output for xlang transforms to confirm all component coders were emitted
Test with a simpler pipeline to isolate which transform produces the broken composite coder

Defensive patterns

Strategy: try-catch

Validate before calling

for _, cc := range c.GetComponentCoderIds() {
    if _, ok := base[cc]; !ok {
        return fmt.Errorf("component coder %q of %q missing", cc, cID)
    }
}

Try / catch

rcc, err := lpUnknownCoders(cc, bundle, base)
if err != nil {
    return fmt.Errorf("composite %q broken: %w", cID, err)
}

Prevention

Validate composite coder trees recursively before execution
For xlang pipelines, inspect expansion output for complete component coders
Isolate failing transforms with minimal repro pipelines

When it happens

Trigger: Traversing a composite coder (e.g. custom or xlang coder) whose GetComponentCoderIds contains an ID missing from the base map or otherwise failing lpUnknownCoders — see error 4666 for the typical root cause.

Common situations: Cross-language pipelines where the expansion service emitted component coders not registered in the pipeline's coder map; deeply nested custom coders with dangling references.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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