apache/beam · error

unencodable type ' ', try to wrap the type as a field in a…

Error message

unencodable type '%v', try to wrap the type as a field in a struct, see https://github.com/apache/beam/issues/23101 for details

What it means

encodeType explicitly rejects reflect.Map and reflect.Array kinds, returning 'unencodable type %v' with a link to beam issue 23101. The graphx protobuf type schema cannot represent raw maps/arrays, so the SDK fails fast at graph-marshalling time rather than producing a corrupt model graph.

Solutions

1. Wrap the map or array as a field in a struct and use the struct as the element type, per issue 23101
2. Use beam.KV or a custom struct instead of a raw map as the PCollection type
3. Register a beam.CustomCoder for the map type
4. Split the map into slices of key/value pairs that are encodable

Example fix

// before
func emit(wordcount map[string]int) { ... }
// after
type WordCount struct { Counts map[string]int }
func emit(wc WordCount) { ... }

if t.Kind() == reflect.Map || t.Kind() == reflect.Array {
	return fmt.Errorf("type %v must be wrapped in a struct before use in a Beam pipeline", t)
}

func mapOrArray(t reflect.Type) bool { return t.Kind() == reflect.Map || t.Kind() == reflect.Array }

if err != nil {
	var encErr = err
	log.Printf("unencodable type: %v", errors.WithContextf(err, "in pipeline"))
	// replace element type with a struct wrapper and resubmit
}

When it happens

Trigger: Any pipeline where a top-level Map or Array reflect.Type is serialized into the job graph — e.g. a PCollection of map[string]int as the direct coder type, or an exported DoFn field/parameter of map or array type.

Common situations: Developers using Go maps as PCollection element types (a very natural pattern) hit this at pipeline construction/submit; also occurs after upgrades when code paths changed to emit map-typed coders.

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

• bad base type
• bad channel direction
• bad element type
• bad field type
• bad parameter type

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/graphx/serialize.go:508

			return nil, errors.WithContextf(wrapped, "encoding channel %v", t)
		}
		dir, err := encodeChanDir(t.ChanDir())
		if err != nil {
			wrapped := errors.Wrap(err, "bad channel direction")
			return nil, errors.WithContextf(wrapped, "encoding channel %v", t)
		}
		return &v1pb.Type{Kind: v1pb.Type_CHAN, Element: elm, ChanDir: dir}, nil

	case reflect.Ptr:
		elm, err := encodeType(t.Elem())
		if err != nil {
			wrapped := errors.Wrap(err, "bad base type")
			return nil, errors.WithContextf(wrapped, "encoding pointer %v", t)
		}
		return &v1pb.Type{Kind: v1pb.Type_PTR, Element: elm}, nil

	case reflect.Map, reflect.Array:
		return nil, errors.Errorf("unencodable type '%v', try to wrap the type as a field in a struct, see https://github.com/apache/beam/issues/23101 for details", t.Kind())

	default:
		return nil, errors.Errorf("unencodable type '%v'", t.Kind())
	}
}

func tryEncodeSpecial(t reflect.Type) (v1pb.Type_Special, bool) {
	switch t {
	case reflectx.Error:
		return v1pb.Type_ERROR, true
	case reflectx.Context:
		return v1pb.Type_CONTEXT, true
	case reflectx.Type:
		return v1pb.Type_TYPE, true

	case typex.EventTimeType:
		return v1pb.Type_EVENTTIME, true
	case typex.WindowType:

View on GitHub (pinned to 12126d8942)