temporalio/temporal · error

nexus operation processor failed

Error message

nexus operation processor failed

What it means

errOpProcessorFailed is a sentinel error returned by the nexusoperations component's Start/Cancel execution paths when the underlying Nexus operation processor (the async task machinery that drives the operation state machine) fails to run. It indicates an internal processing failure rather than a problem with the caller's request or the remote Nexus endpoint. It is also used by outcome-tagging helpers (startCallOutcomeTag/cancelCallOutcomeTag) to classify metrics for processor failures.

Solutions

1. Check history service logs around the tagged operation outcome for the underlying processor error; the sentinel wraps/masks the real cause
2. Verify the Nexus endpoint registration and that ClientProvider can construct a client for the namespace/service
3. Confirm all history service nodes run the same Temporal server version to avoid state-machine processor incompatibilities
4. Retry the workflow operation; if persistent, inspect the operation HSM state in the workflow and file an issue with the full logs

// pseudo: on Start/Cancel failure tagged as processor failure, retry with backoff; alert if persistent
err := exec.Start(ctx, req)
if errors.Is(err, errOpProcessorFailed) { scheduleRetryWithBackoff() }

When it happens

Trigger: Calling Start or Cancel on a nexusoperations executor when the operation processor returns an error, or when isDestinationDown-adjacent processing hits a processor failure while preparing an outbound Nexus call.

Common situations: Internal state-machine task execution bugs, corrupt or unexpected persisted operation state, failures initializing the Nexus client via the ClientProvider, or version-skew between history nodes running different processor implementations.

Related errors

• cannot resolve Nexus endpoints partition owner
• cannot serialize HSM task. unable to cast to expected type
• completion token has no operation state machine reference
• no nexus context set on context
• batch operation stats are not present in the memo

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

Appendix: source

Thrown at components/nexusoperations/executors.go:52

	"go.temporal.io/server/common/resource"
	"go.temporal.io/server/service/history/consts"
	"go.temporal.io/server/service/history/hsm"
	queueserrors "go.temporal.io/server/service/history/queues/errors"
	"go.uber.org/fx"
)

type operationTimeoutBelowMinError struct {
	timeoutType enumspb.TimeoutType
}

func (o *operationTimeoutBelowMinError) Error() string {
	return fmt.Sprintf("not enough time to execute another request before %s timeout", o.timeoutType.String())
}

var ErrInvalidOperationToken = errors.New("invalid operation token")
var ErrResponseBodyTooLarge = errors.New("http: response body too large")
var errRequestTimedOut = errors.New("request timed out")
var errOpProcessorFailed = errors.New("nexus operation processor failed")

const maxDuration = time.Duration(1<<63 - 1)

// ClientProvider provides a nexus client for a given endpoint.
type ClientProvider func(ctx context.Context, namespaceID string, entry *persistencespb.NexusEndpointEntry, service string) (*nexusrpc.HTTPClient, error)

type TaskExecutorOptions struct {
	fx.In

	Config                 *Config
	NamespaceRegistry      namespace.Registry
	MetricsHandler         metrics.Handler
	Logger                 log.Logger
	CallbackTokenGenerator *commonnexus.CallbackTokenGenerator
	ClientProvider         ClientProvider
	EndpointRegistry       commonnexus.EndpointRegistry
	HTTPTraceProvider      commonnexus.HTTPClientTraceProvider
	HistoryClient          resource.HistoryClient

View on GitHub (pinned to bde624efd1)