apache/beam · error

unexpected type kind %v

Error message

unexpected type kind %v

What it means

decodeType received a v1pb.Type whose Kind field does not match any known Type_* enum case (primitive, slice, map, chan, pointer, special, external). This indicates a malformed or forward-incompatible type proto.

Source

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

	case v1pb.Type_SPECIAL:
		ret, err := decodeSpecial(t.Special)
		if err != nil {
			wrapped := errors.Wrap(err, "bad element")
			return nil, errors.WithContextf(wrapped, "decoding type %v", t)
		}
		return ret, nil

	case v1pb.Type_EXTERNAL:
		ret, ok := runtime.LookupType(t.ExternalKey)
		if !ok {
			err := errors.Errorf("external key not found %v", t.ExternalKey)
			return nil, errors.WithContextf(err, "decoding type %v", t)
		}
		return ret, nil

	default:
		err := errors.Errorf("unexpected type kind %v", t.Kind)
		return nil, errors.WithContextf(err, "failed to decode type %v", t)
	}
}

func decodeSpecial(s v1pb.Type_Special) (reflect.Type, error) {
	switch s {
	case v1pb.Type_ERROR:
		return reflectx.Error, nil
	case v1pb.Type_CONTEXT:
		return reflectx.Context, nil
	case v1pb.Type_TYPE:
		return reflectx.Type, nil

	case v1pb.Type_EVENTTIME:
		return typex.EventTimeType, nil
	case v1pb.Type_WINDOW:
		return typex.WindowType, nil
	case v1pb.Type_BUNDLEFINALIZATION:

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam Go SDK used for decoding to match (or exceed) the encoding version
2. Re-serialize the pipeline with the version that will consume it
3. Inspect the proto's Type.Kind value and confirm it is a valid v1pb.Type_Kind
4. If upgrading isn't possible, avoid emitting the new type kind (e.g., use registered external types)

Example fix

// before: old SDK decoding new-format graph
graphx.DecodeGraph(data) // 'unexpected type kind 12'

// after
go get github.com/apache/beam/sdks/go@latest // then rebuild the worker

if err := graphx.DecodeGraph(data, &p); err != nil {
    if strings.Contains(err.Error(), "unexpected type kind") {
        return fmt.Errorf("graph encoded by incompatible Beam version; upgrade decoder: %w", err)
    }
    return err
}

When it happens

Trigger: Decoding a pipeline proto with an unrecognized Type.Kind value — typically from a newer Beam version that introduced a new kind, or a corrupted/truncated proto where Kind holds garbage.

Common situations: Version skew between encoder (newer Beam) and decoder (older Beam); manually crafted or corrupted pipeline JSON; wire format changes.

Related errors

• Failed to convert PipelineOptions to JSON
• varint too long
• empty type
• error encoding byte: %v
• error encoding pane %v: non-speculative index value must be

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