temporalio/temporal · error

completion token has no operation state machine reference

Error message

completion token has no operation state machine reference

What it means

Raised by scheduledEventIDFromHSMRef when a Nexus completion token's payload contains no operation state machine reference (the ref's key or type is not an HSM machine reference), so the scheduled event ID cannot be extracted. Callers like identityFromHSM need this ID to build the workflow identity for completing an operation.

Source

Thrown at nexusworkflowref/nexusworkflowref.go:145

			MachineInitialVersionedTransition:    &persistencespb.VersionedTransition{},
			MachineLastUpdateVersionedTransition: &persistencespb.VersionedTransition{},
		},
		RequestId: id.requestID,
	}
}

func scheduledEventIDFromHSMRef(ref *persistencespb.StateMachineRef) (int64, error) {
	for _, key := range ref.GetPath() {
		if key.GetType() != nexusoperations.OperationMachineType {
			continue
		}
		scheduledEventID, err := strconv.ParseInt(key.GetId(), 10, 64)
		if err != nil {
			return 0, fmt.Errorf("invalid operation state machine id %q: %w", key.GetId(), err)
		}
		return scheduledEventID, nil
	}
	return 0, errors.New("completion token has no operation state machine reference")
}

func scheduledEventIDFromComponentPath(path []string) (int64, error) {
	if len(path) != 2 || path[0] != operationsFieldName {
		return 0, fmt.Errorf("unexpected nexus operation component path %v", path)
	}
	scheduledEventID, err := strconv.ParseInt(path[1], 10, 64)
	if err != nil {
		return 0, fmt.Errorf("invalid scheduled event id %q: %w", path[1], err)
	}
	return scheduledEventID, nil
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Regenerate the completion token from the Nexus operation task/start response rather than constructing it manually
2. Verify the token originates from the same workflow run that scheduled the operation
3. Check server versions: tokens from pre-HSM server versions are incompatible; fail over or re-run the operation
4. Inspect the token's ref fields - ensure the state machine key ID is present and parses as an int64 scheduled event ID

// before using a completion token, verify it carries an HSM ref:
if token.GetRef() == nil || token.GetRef().GetStateMachines() == nil || len(token.GetRef().GetStateMachines().GetComponent()) == 0 {
    return errors.New("token missing operation state machine reference")
}

func hasHSMRef(t *nexuspb.CompletionToken) bool {
  return t != nil && t.GetRef() != nil && t.GetRef().GetStateMachines() != nil && t.GetRef().GetStateMachines().GetId() != ""
}

When it happens

Trigger: Completing/canceling a Nexus operation with a completion token that was not generated from an HSM operation reference - e.g. a malformed, hand-crafted, or from-an-older-version token whose Ref/ComponentRef is absent.

Common situations: Worker or custom code constructing completion tokens manually, tokens persisted before the HSM-based operation tracking was introduced, or copying tokens between workflows/namespaces.

Related errors

• cannot serialize HSM task. unable to cast to expected type
• nexus operation processor failed
• no nexus context set on context
• task has no deadline or destination
• cannot resolve Nexus endpoints partition owner: %w

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