Troubleshooting
Find the symptom, read the cause, take the action. Each row names the check that confirms the cause.
The host does not start
| Symptom | Cause | Check and action |
|---|---|---|
| “The PostgreSQL workflow backend requires a connection string and none is configured” | STELLAOPS_POSTGRES_WORKFLOW_CONNECTION is not set where the host runs | Set it in the environment or the secret store of that host |
| “Workflow backend provider ‘X’ is selected but no backend plugin registered it” | WorkflowBackend:Provider names a store whose library is not registered | Register the store library, or correct the provider name (Postgres, Mongo) |
| “Workflow signal driver provider ‘X’ is selected but no signal driver plugin registered it” | WorkflowSignalDriver:Provider is Redis without AddWorkflowRedisSignaling | Register the driver, or set Native |
| “WorkflowRuntime.MaxMapConcurrency must be between 1 and 64” (and similar) | An engine option is outside its range | Correct the value (Configuration reference) |
The schema migration fails with permission denied for database | The role may not create the workflow schema | Grant CREATE on the database once, or create the schema for the role (Persistence and signals) |
| The build fails with WF001 to WF010 | The analyzer found C# in a Spec that cannot be a canonical definition | Read the message; the analyzer reference gives the fix |
| The build fails with WF020 | A class implements IDeclarativeWorkflow<T> without a Spec property | Add the Spec (analyzer reference) |
| The build reports WF021, or fails on it with warnings as errors | The generator cannot evaluate a construct at build time; the workflow is left out of the build-time bundle and the publisher compiles it when it starts | Nothing for a workflow registered in code; or <WarningsNotAsErrors>WF021</WarningsNotAsErrors> (analyzer reference) |
The publisher reports a workflow as failed with WFCD codes | The workflow uses a C# delegate, which has no canonical definition | Use the WorkflowExpr form (Defining workflows) |
A workflow does not behave as written
| Symptom | Cause | Check and action |
|---|---|---|
A start answers 404 with WorkflowDefinitionNotFound | The workflow is not registered in this host, or the name differs | GET /api/workflow/definitions lists the registered workflows |
| An imported definition cannot be started | Imports are stored, not registered | Register the workflow in code (Governed activation and publishing) |
The host stops at start, or a definition is refused, with WFIMP010 ... Required workflow module 'transport.endpoint' is not installed | No transport package for an address kind the workflow uses | Register the transport (Calling services); a test with its own transport registers the module with AddWorkflowModule |
| A step after a timer or a signal never runs | The signal pump does not run on any node | Call AddWorkflowEngineHostedServices on at least one node; check GET /api/workflow/signals/pump/stats |
| With the Redis driver, timers start up to 30 seconds after they fall due | A timer is announced when it is scheduled, not when it falls due; the pump finds it on its next look at the store | Lower WorkflowSignalDriver:Redis:BlockingWaitSeconds (Persistence and signals) |
| An instance stops and its signal is in the dead letters | A step failed MaxDeliveryAttempts times | Read the error, fix the cause, replay (Operations) |
A state change is refused with WORKFLOW_STATE_JSON_* | The state is too large, too deep, or has a property name with a forbidden fragment | Keep large data and secrets out of the state |
Calls fail
| Symptom | Cause | Check and action |
|---|---|---|
| “Endpoint transport has no base address for service ‘X’” | WorkflowEndpointTransport:Services:X:Url is missing | Configure the service |
| The publisher fails every workflow with 404 | Endpoint or CommandPath does not reach the target’s import route | Endpoint is the target’s base URL; CommandPath defaults to /api/workflow/definitions/import |
The host stops at start with an options validation error for WorkflowPublisher | An enabled publisher has no absolute http or https Endpoint, or another option breaks a rule | Set the key the error names, or Enabled: false or DryRun: true (Governed activation and publishing) |
| An error names a missing transport for a kind | The transport package of that kind is not registered | Register it (Calling services) |
A rabbit call fails at once | WorkflowRabbitTransport:HostName is not set | Configure the broker |
A rabbit command runs the timeout branch | No reply within ReplyTimeoutSeconds, or the step’s timeoutSeconds passed | Check the consumer and the reply mode |
| A call returns 404 | The path in the definition, or the base URL, is wrong | The request goes to the base URL joined with the path; check both |
HTTP API
| Symptom | Cause | Check and action |
|---|---|---|
| 401 on every route | No token, an expired token, another issuer or audience | Check Authentication:Schemes:Bearer and the token |
| 403 on a route | The token lacks the scope of the route’s policy | Hosting |
| 403 although the token has the scope | The scopes are in a claim the handler does not read | Put them in scope (space-delimited) or scp; set MapInboundClaims = false |
A task action answers 403 with WorkflowTaskActionDenied | The caller’s roles do not include a role of the task | Check the token’s role claims and WorkflowAuthorization:RoleClaimTypes |
A task action answers 403 with WorkflowActorUnresolved | The token has none of the actor ID claim types | Check WorkflowAuthorization:ActorIdClaimTypes (default sub, then the name identifier) |
| An import or activation answers 409 or 400 | A governance refusal, named in the body’s error (WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT, WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST, and others) | Governed activation and publishing, Refusals |
| A request answers 500 | WorkflowRuntimeFailed in the body, or no body: an unexpected error | The host log has the exception |
| A diagram request takes minutes | The default layout effort is Best | Ask for layoutEffort=Draft or Balanced (Rendering) |
Licence messages
| Message | Meaning |
|---|---|
Status within-free-limit | The count is at or below the notice level; information only |
Status above-notice-level | The count is above the notice level and within the free limit; a notice, nothing is refused |
Status record-matches | A licence entry covers the running version, and the count is within its capacity or the free limit; information only |
Status embedded-scope-not-established | An embedded licence entry decides; the local record does not establish its product and end-customer scope. Check the Order; nothing is refused |
Status no-matching-record, count-exceeds-recorded-capacity, development-build, count-unavailable | See Licensing; nothing is refused, stopped or restricted |
Collecting information for support
- The package version of every
StellaOps.Workflow*package (all must be the same). - The host’s configuration with secrets removed.
- The log of the start and of the failing operation, at
Information. GET /readyz,GET /api/workflow/signals/pump/stats, and the dead letters of the instance.
