dapr/dapr · error

MCPServer %q: failed to register workflows: %w

Error message

MCPServer %q: failed to register workflows: %w

What it means

Thrown when the MCPServer was validated, committed to the component store, and logged as loaded, but the registerMCPServer hook (workflow engine registration for the server's workflows) returned an error. Note the deliberate ordering: the server is already observable via the metadata API even when this fails, mirroring pre-refactor behaviour under IgnoreErrors.

Source

Thrown at pkg/runtime/processor/loops/mcpserver/mcpserver.go:137

	h.secret.ProcessResource(ctx, &s)
	if s.Spec.Endpoint.Stdio != nil {
		h.secret.ProcessResource(ctx, mcpStdioEnvResource{MCPServer: &s})
	}

	// Commit to compstore before workflow registration. Matches the
	// pre-refactor behaviour: under IgnoreErrors=true, an MCPServer whose
	// workflow registration fails is still considered "loaded" and
	// observable via the metadata API.
	h.compStore.AddMCPServer(s)
	log.Infof("MCPServer loaded: %s", s.LogName())

	if h.registerMCPServer == nil {
		sendResult(ev.Result, nil)
		return
	}
	if err := h.registerMCPServer(ctx, s); err != nil {
		sendResult(ev.Result, fmt.Errorf("MCPServer %q: failed to register workflows: %w", s.Name, err))
		return
	}
	sendResult(ev.Result, nil)
}

func (h *Handler) handleDelete(ev *loops.DeleteMCPServer) {
	h.compStore.DeleteMCPServer(ev.Name)
	if h.unregisterMCPServer != nil {
		h.unregisterMCPServer(ev.Name)
	}
	if ev.Done != nil {
		close(ev.Done)
	}
}

// mcpStdioEnvResource is a thin adapter that wraps an MCPServer and overrides
// NameValuePairs to return Spec.Endpoint.Stdio.Env instead of the HTTP
// transport headers.

View on GitHub (pinned to 74ad417027)

Solutions

1. Check the wrapped error from the workflow engine in the same log line to identify the rejected workflow
2. Verify the workflow engine is enabled and initialized in this daprd build (workflow feature/flags) before loading MCPServer resources
3. Remove or rename duplicate workflow registrations referenced by the MCPServer
4. If the MCPServer's workflows are optional, treat this error as non-fatal: the server stays loaded and only workflow invocation is unavailable

// Before loading, confirm the workflow engine is up if your MCPServer declares workflows
if mcps.Spec.HasWorkflows() && !workflowEngine.Ready() {
    return fmt.Errorf("defer applying %s: workflow engine not ready", mcps.Name)
}

Treat as non-fatal: the MCPServer stays loaded and observable via the metadata API; log the error, keep serving tool/list requests, and retry workflow registration on the next reconcile of the resource.

When it happens

Trigger: Calling the component add path for an MCPServer when the workflow-engine-backed registerMCPServer callback fails: workflow engine not initialized, workflow registration name collisions for the same MCPServer, or an engine-side rejection while registering the server's workflow handlers.

Common situations: Mixing MCPServer resources with an embedded workflow engine in a build where workflow registration is partially configured; re-applying an MCPServer with changed workflow definitions during hot reload; version skew between daprd and the workflow engine.

Related errors

• process MCPServer %s error: %s
• flush MCP servers: %w
• hook %q failed for tool %q on MCPServer %q: %w
• mutating hook %q failed for MCPServer %q: %w
• hook %q failed for MCPServer %q: %w

AI-assisted analysis of dapr/dapr@74ad417027 (2026-08-16). Data as JSON: /api/errors/a8b4ba9edef245b4. Report an issue: GitHub.