Unrecognized state type

Error message

Unrecognized state type %v for state %v. Currently the only supported statetypes are state.Value, state.Combining, state.Bag, state.Set, state.Map, and state.OrderedList

What it means

Beam Go restricts pipeline state to a known set of types: state.Value, state.Combining, state.Bag, state.Set, state.Map, and state.OrderedList. When a State struct attached to a DoFn reports a StateType outside this set, validation throws this error because the runner cannot serialize or manage the unknown state kind.

Solutions

Replace the custom state with one of the supported types: state.Value, state.Bag, state.Combining, state.Set, state.Map, or state.OrderedList.
Align Beam SDK versions (go.mod) so the state type is recognized by the validator.
Remove the invalid State field if it isn't actually needed.

Example fix

// before
type CacheFn struct {
    LRU state.Custom[...] // unknown state type
}
// after
type CacheFn struct {
    Cache state.Map[string, []byte]
}

Defensive patterns

Strategy: validation

Validate before calling

// only use supported state generics
var _ state.Value[string, int]
var _ state.Bag[string]
var _ state.Map[string, []byte]
var _ state.Set[string]
var _ state.OrderedList[int]

Type guard

func isSupportedState(s state.PipelineState) bool {
    switch s.StateType() {
    case state.TypeValue, state.TypeBag, state.TypeCombining, state.TypeSet, state.TypeMap, state.TypeOrderedList:
        return true
    }
    return false
}

Try / catch

if err := beam.Run(ctx, p); err != nil {
    if strings.Contains(err.Error(), "Unrecognized state type") {
        log.Fatalf("swap the custom state for a supported state type: %v", err)
    }
    return err
}

Prevention

Only use the six documented state kinds; never hand-roll custom state types
Keep go.mod Beam SDK version consistent with runner/runtime versions
Read the state API docs before inventing new state abstractions

When it happens

Trigger: Attaching a custom struct implementing the state interface with an unrecognized StateType(), or using a state type added in a newer Beam version while running an older runtime (or vice versa) so the type constant isn't in the validator's whitelist.

Common situations: Implementing a custom PipelineState abstraction; Beam version mismatch between pipeline construction and the fn.go validation code; hand-written state structs copied incorrectly.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/graph/fn.go:1372

				"All stateful DoFns must take a key/value pair as an input.")
		}
		if len(ps) == 0 {
			err := errors.Errorf("ProcessElement uses a StateProvider, but noState structs are attached to the DoFn")
			return errors.SetTopLevelMsgf(err, "ProcessElement uses a StateProvider, but no State structs are "+
				"attached to the DoFn. Ensure that you are including the State structs you're using to read/write"+
				"global state as public uppercase member variables.")
		}
		stateKeys := make(map[string]state.PipelineState)
		for _, s := range ps {
			k := s.StateKey()
			if orig, ok := stateKeys[k]; ok {
				err := errors.Errorf("Duplicate state key %v", k)
				return errors.SetTopLevelMsgf(err, "Duplicate state key %v used by %v and %v. Ensure that state keys are"+
					"unique per DoFn", k, orig, s)
			}
			t := s.StateType()
			if t != state.TypeValue && t != state.TypeBag && t != state.TypeCombining && t != state.TypeSet && t != state.TypeMap && t != state.TypeOrderedList {
				err := errors.Errorf("Unrecognized state type %v for state %v", t, s)
				return errors.SetTopLevelMsgf(err, "Unrecognized state type %v for state %v. Currently the only supported state"+
					"types are state.Value, state.Combining, state.Bag, state.Set, state.Map, and state.OrderedList", t, s)
			}
			stateKeys[k] = s
		}
	} else {
		if len(ps) > 0 {
			err := errors.Errorf("ProcessElement doesn't use a StateProvider, but State structs are attached to "+
				"the DoFn: %v", ps)
			return errors.SetTopLevelMsgf(err, "ProcessElement doesn't use a StateProvider, but State structs are "+
				"attached to the DoFn: %v\nEnsure that you are using the StateProvider to perform any reads or writes"+
				"of pipeline state.", ps)
		}
	}

	return nil
}

View on GitHub (pinned to 12126d8942)