apache/beam · error

failed to decode special type, unknown type

Error message

failed to decode special type, unknown type %v

What it means

decodeSpecial was given a v1pb.Type_Special enum value it cannot map to a typex.* special type (XType, YType, ZType, etc.). Raised from the default branch when the special-kind payload of a Type node is unknown to this Beam version.

Solutions

1. Upgrade the Beam Go SDK so the newer special type is recognized
2. Verify the pipeline data wasn't truncated or corrupted (checksum / re-export)
3. Re-encode the pipeline using the older SDK version that the decoder supports
4. Check the Special enum value in the proto against the cases in decodeSpecial

Example fix

// before
beamx.Unmarshal(dataFromNewerSDK, &p) // unknown special type

// after
// pin both producer and consumer to the same Beam version
go get github.com/apache/beam/sdks/go@v2.60.0

if err := beamx.Unmarshal(data, &p); err != nil {
    if strings.Contains(err.Error(), "unknown type") {
        return fmt.Errorf("unknown special type — SDK version skew or corrupt data: %w", err)
    }
    return err
}

When it happens

Trigger: decodeType processes a Type_SPECIAL node whose t.Special value falls through all known cases; called only by decodeType.

Common situations: Graph serialized by a newer Beam SDK that added a new special type; corrupted pipeline data; hand-assembled proto with an out-of-range Special enum.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• bad input kind
• external key not found
• bad combinefn
• bad decoding function
• bad encoding function

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

Appendix: source

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

		return typex.WindowedValueType, nil

	case v1pb.Type_T:
		return typex.TType, nil
	case v1pb.Type_U:
		return typex.UType, nil
	case v1pb.Type_V:
		return typex.VType, nil
	case v1pb.Type_W:
		return typex.WType, nil
	case v1pb.Type_X:
		return typex.XType, nil
	case v1pb.Type_Y:
		return typex.YType, nil
	case v1pb.Type_Z:
		return typex.ZType, nil

	default:
		return nil, errors.Errorf("failed to decode special type, unknown type %v", s)
	}
}

func decodeTypes(list []*v1pb.Type) ([]reflect.Type, error) {
	var ret []reflect.Type
	for _, elm := range list {
		t, err := decodeType(elm)
		if err != nil {
			return nil, err
		}
		ret = append(ret, t)
	}
	return ret, nil
}

func encodeInts(offsets []int) []int32 {
	var ret []int32
	for _, elm := range offsets {

View on GitHub (pinned to 12126d8942)