apache/beam · error

unexpected inbound type

Error message

unexpected inbound type: %v

What it means

tryBindInbound throws this when a composite inbound type (like KV, CoGBK, or Windowed) has a component type not supported by the binder's composite switch. Only a known set of composite component types (Bool, Bytes, etc. per the switch) can be bound. The error reports the raw inbound type so the mismatch is visible.

Solutions

1. Ensure composite components use supported/registered types (primitives, registered coders).
2. Register a coder for the custom component type with beam.RegisterCoder before binding.
3. Decode/encode the composite into a supported shape (e.g. map values to primitives) before using it as a side input.
4. Check t.Type() in the message to identify the offending component and replace it.

Example fix

// before: KV<MyKey, MyUnregisteredStruct> side input
// after: register coder
type MyStruct struct{ A int }
beam.RegisterCoder(reflect.TypeOf(MyStruct{}), encodeMyStruct, decodeMyStruct)

// Go: verify composite components are registered/supported before binding
for _, c := range t.Components() {
    if reflect.New(c).Interface() == nil {
        return fmt.Errorf("component %v must be a registered, non-interface type", c)
    }
}

When it happens

Trigger: Building a side input or main input whose composite FullType contains a component type that is not in the binder's supported composite-type list, e.g. a KV of custom structs where the binder expects primitive/registered kinds.

Common situations: Side inputs built from PCollections of unregistered custom types; windowed side inputs with unusual value types; mixing SDK versions where a type kind was added later.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• unexpected composite inbound type
• bind conflict for : !=
• bind conflict for : !=
• cannot substitute type
• optional generic parameter not bound

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/graph/bind.go:302

						return nil, kind, errors.Errorf("values of %v cannot bind to %v", t, args[i])
					}
					components = append(components, typex.New(trimmed[0]))

				case funcx.FnReIter:
					values, _ := funcx.UnfoldReIter(args[i].T)
					trimmed := trimIllegal(values)
					if len(trimmed) != 1 {
						return nil, kind, errors.Errorf("values of %v cannot bind to %v", t, args[i])
					}
					components = append(components, typex.New(trimmed[0]))
				default:
					return nil, kind, errors.Errorf("values of %v cannot bind to %v", t, args[i])
				}
			}
			other = typex.NewCoGBK(components...)

		default:
			return nil, kind, errors.Errorf("unexpected inbound type: %v", t.Type())
		}

	default:
		return nil, kind, errors.Errorf("unexpected inbound class: %v", t.Class())
	}

	if !typex.IsStructurallyAssignable(t, other) {
		return nil, kind, errors.Errorf("%v is not assignable to %v", t, other)
	}
	return other, kind, nil
}

func inboundArity(t typex.FullType, isMain bool) (int, error) {
	if t.Class() == typex.Composite {
		switch t.Type() {
		case typex.KVType:
			if isMain {
				return 2, nil

View on GitHub (pinned to 12126d8942)