temporalio/temporal · error · Internal

%w: %w

Error message

%w: %w

What it means

The same validateStateMachineRef path, for the failure to look up a node that DOES exist in the path but whose lookup failed for a reason other than ErrStateMachineNotFound. It wraps serviceerror.NewInternal("node lookup failed") with the underlying error — an unexpected internal failure in the HSM tree traversal.

Source

Thrown at service/history/statemachine_environment.go:256

		len(ms.GetExecutionInfo().TransitionHistory) == 0 {
		// Transtion history was disabled when the ref is generated,
		// fallback to the old validation logic.
		return e.validateStateMachineRefWithoutTransitionHistory(ms, ref, potentialStaleState)
	}

	err := transitionhistory.StalenessCheck(
		ms.GetExecutionInfo().GetTransitionHistory(),
		ref.StateMachineRef.MutableStateVersionedTransition,
	)
	if err != nil {
		return err
	}
	node, err := ms.HSM().Child(ref.StateMachinePath())
	if err != nil {
		if errors.Is(err, hsm.ErrStateMachineNotFound) {
			return fmt.Errorf("%w: %w", consts.ErrStaleReference, err)
		}
		return fmt.Errorf("%w: %w", serviceerror.NewInternal("node lookup failed"), err)
	}

	if node.InternalRepr().GetInitialVersionedTransition().TransitionCount == 0 {
		// transition history was disabled after the ref was generated and mutable state got rebuilt.
		// fallback to the old validation logic.
		return e.validateStateMachineRefWithoutTransitionHistory(ms, ref, potentialStaleState)
	}

	if transitionhistory.Compare(
		ref.StateMachineRef.MachineInitialVersionedTransition,
		node.InternalRepr().GetInitialVersionedTransition(),
	) != 0 {
		return fmt.Errorf("%w: initial versioned transition mismatch", consts.ErrStaleReference)
	}

	if ref.StateMachineRef.GetMachineLastUpdateVersionedTransition().GetTransitionCount() == 0 {
		// Transition history was disabled when the node was last updated.
		if ref.Validate == nil {

View on GitHub (pinned to bde624efd1)

Solutions

1. Inspect the wrapped underlying error to identify the actual lookup failure
2. Verify mutable state integrity for the workflow; consider replaying or resetting the workflow
3. Report/fix upstream if the HSM path is being constructed with an invalid format

err := env.validateStateMachineRef(ms, ref, stale)
if err != nil {
	var internal *serviceerror.Internal
	if errors.As(err, &internal) {
		// unexpected node lookup failure: log with wrapped cause and alert
	}
	return err
}

When it happens

Trigger: ms.HSM().Child(ref.StateMachinePath()) returns an error that is not hsm.ErrStateMachineNotFound — e.g. malformed path, corrupt mutable state tree, or an internal persistence/deserialization problem during child traversal.

Common situations: Corrupted workflow mutable state after a failed upgrade or partial write; path format mismatch between code versions; bugs in HSM path construction.

Related errors

• ErrStaleReference
• ErrStaleState
• Failed to get HSM operation log: %v
• ErrInvalidTransition
• failed to deserialize component: %w

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/ef324c7198234bdf. Report an issue: GitHub.