apache/beam · error

not a unsigned integer type: %v

Error message

not a unsigned integer type: %v

What it means

Error returned by NewVarUintZ when asked for a zig-zag uvarint coder for a type whose reflect.Kind is not an unsigned integer (Uint..Uintptr). The constructor only supports unsigned kinds; passing a signed or non-integer type (the adjacent NewVarIntZ handles signed types) hits this guard. Typically reached via coder inference on a struct field of unsupported type.

Source

Thrown at sdks/go/pkg/beam/core/runtime/coderx/varint.go:46

// NewVarIntZ returns a varint coder for the given integer type. It uses a zig-zag scheme,
// which is _different_ from the Beam standard coding scheme.
func NewVarIntZ(t reflect.Type) (*coder.CustomCoder, error) {
	switch t.Kind() {
	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
		return coder.NewCustomCoder("varintz", t, encVarIntZ, decVarIntZ)
	default:
		return nil, errors.Errorf("not a signed integer type: %v", t)
	}
}

// NewVarUintZ returns a uvarint coder for the given integer type. It uses a zig-zag scheme,
// which is _different_ from the Beam standard coding scheme.
func NewVarUintZ(t reflect.Type) (*coder.CustomCoder, error) {
	switch t.Kind() {
	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
		return coder.NewCustomCoder("varuintz", t, encVarUintZ, decVarUintZ)
	default:
		return nil, errors.Errorf("not a unsigned integer type: %v", t)
	}
}

func encVarIntZ(v typex.T) []byte {
	var val int64
	switch n := v.(type) {
	case int:
		val = int64(n)
	case int8:
		val = int64(n)
	case int16:
		val = int64(n)
	case int32:
		val = int64(n)
	case int64:
		val = n
	default:
		panic(fmt.Sprintf("received unknown value type: want a signed integer:, got %T", n))

View on GitHub (pinned to 12126d8942)

Solutions

1. Use NewVarIntZ for signed integer kinds instead.
2. Pass an unsigned integer type such as reflect.TypeOf(uint64(0)).
3. Audit coder registrations so each field's Kind matches the coder constructor used.

Example fix

// before
c, err := coderx.NewVarUintZ(reflect.TypeOf(int64(0)))
// after
c, err := coderx.NewVarIntZ(reflect.TypeOf(int64(0)))

func canUseVarUintZ(t reflect.Type) bool {
    switch t.Kind() {
    case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
        return true
    }
    return false
}

func isUnsignedIntKind(t reflect.Type) bool {
    k := t.Kind()
    return k >= reflect.Uint && k <= reflect.Uint64
}

c, err := coderx.NewVarUintZ(t)
if err != nil {
    return fmt.Errorf("expected unsigned int type, got %s: %w", t, err)
}

When it happens

Trigger: Calling coderx.NewVarUintZ(t) with a signed integer, float, or non-numeric reflect.Type; typically from inferCoder with a mismatched field type.

Common situations: Passing int/int64 to the uint coder; copying a coder registration from a signed field to an unsigned one without updating the constructor.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• not a float type: %v
• not a signed integer type: %v
• received unknown value type: want []byte, got %T
• coder type %v must be identical to node type %v
• GroupByKey requires its input to use KvCoder

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