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.

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)

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 serialize HSM task. unable to cast to expected type
• completion token has no operation state machine reference
• no nexus context set on context
• cannot resolve Nexus endpoints partition owner: %w
• link type is empty

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