{"record":{"id":"7268096463ab0edb","repo":"temporalio/temporal","slug":"errstalereference","errorCode":"ErrStaleReference","errorMessage":"%w: %w","messagePattern":"%w: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/history/statemachine_environment.go","lineNumber":254,"sourceCode":"\t\t(ref.StateMachineRef.MachineLastUpdateVersionedTransition != nil &&\n\t\t\tref.StateMachineRef.MachineLastUpdateVersionedTransition.TransitionCount == 0) ||\n\t\tlen(ms.GetExecutionInfo().TransitionHistory) == 0 {\n\t\t// Transtion history was disabled when the ref is generated,\n\t\t// fallback to the old validation logic.\n\t\treturn e.validateStateMachineRefWithoutTransitionHistory(ms, ref, potentialStaleState)\n\t}\n\n\terr := transitionhistory.StalenessCheck(\n\t\tms.GetExecutionInfo().GetTransitionHistory(),\n\t\tref.StateMachineRef.MutableStateVersionedTransition,\n\t)\n\tif err != nil {\n\t\treturn err\n\t}\n\tnode, err := ms.HSM().Child(ref.StateMachinePath())\n\tif err != nil {\n\t\tif errors.Is(err, hsm.ErrStateMachineNotFound) {\n\t\t\treturn fmt.Errorf(\"%w: %w\", consts.ErrStaleReference, err)\n\t\t}\n\t\treturn fmt.Errorf(\"%w: %w\", serviceerror.NewInternal(\"node lookup failed\"), err)\n\t}\n\n\tif node.InternalRepr().GetInitialVersionedTransition().TransitionCount == 0 {\n\t\t// transition history was disabled after the ref was generated and mutable state got rebuilt.\n\t\t// fallback to the old validation logic.\n\t\treturn e.validateStateMachineRefWithoutTransitionHistory(ms, ref, potentialStaleState)\n\t}\n\n\tif transitionhistory.Compare(\n\t\tref.StateMachineRef.MachineInitialVersionedTransition,\n\t\tnode.InternalRepr().GetInitialVersionedTransition(),\n\t) != 0 {\n\t\treturn fmt.Errorf(\"%w: initial versioned transition mismatch\", consts.ErrStaleReference)\n\t}\n\n\tif ref.StateMachineRef.GetMachineLastUpdateVersionedTransition().GetTransitionCount() == 0 {","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/service/history/statemachine_environment.go#L236-L272","documentation":"validateStateMachineRef fails when a stored state-machine reference can no longer be resolved: the HSM child node for ref.StateMachinePath() is not found. It wraps hsm.ErrStateMachineNotFound with consts.ErrStaleReference, meaning the reference points at state that no longer exists (deleted, rebuilt, or never replicated).","triggerScenarios":"executeSingleStateMachineTimer (or another caller) validates a task's state machine ref; ms.HSM().Child(ref.StateMachinePath()) returns hsm.ErrStateMachineNotFound. With transition history enabled, this is unconditionally treated as stale.","commonSituations":"State machine deleted (e.g. activity canceled/completed) between ref generation and timer execution; mutable state rebuilt without transition history; cross-cluster replication lag so the node hasn't arrived yet.","solutions":["Treat as stale: discard the timer/task; the state machine it targeted no longer exists","Check replication lag or state rebuild events for the workflow if this occurs unexpectedly","If the node should exist, inspect the workflow's mutable state / transition-history settings for a rebuild that dropped the node"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isStaleRef(err error) bool { return errors.Is(err, consts.ErrStaleReference) }","tryCatchPattern":"err := env.validateStateMachineRef(ms, ref, stale)\nif err != nil && errors.Is(err, consts.ErrStaleReference) {\n\t// discard the timer/task; ref points at deleted state\n\treturn nil\n}","preventionTips":["Re-validate refs immediately before use; keep ref lifetimes short","Detect and discard tasks for already-deleted state machines","Monitor mutable-state rebuild frequency"],"tags":["go","chasm","hsm","stale-reference"],"backgroundTag":"stale-state-machine-reference","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}