mirror of
https://github.com/keycloak/keycloak.git
synced 2026-04-15 22:09:46 -04:00
7e8eb64a52
- also add workflows as supported in release notes Closes #47692 Signed-off-by: Stefan Guilhen <sguilhen@redhat.com>
77 lines
4.3 KiB
Text
77 lines
4.3 KiB
Text
[id="troubleshooting-workflows_{context}"]
|
|
|
|
[[_troubleshooting_workflows_]]
|
|
= Troubleshooting workflows
|
|
|
|
When workflows are not behaving as expected, server logs are the primary tool for understanding what is happening.
|
|
The workflow engine logs detailed information about workflow lifecycle events, step execution, and errors.
|
|
|
|
== Enabling workflow debug logging
|
|
|
|
By default, the workflow engine logs warnings and errors. To see the full execution flow, enable `DEBUG` level
|
|
logging for the `org.keycloak.models.workflow` category by setting the following server configuration option:
|
|
|
|
--log-level=org.keycloak.models.workflow:debug
|
|
|
|
This enables debug logging for the workflow engine, all step providers, and the workflow state provider.
|
|
|
|
== What to look for in the logs
|
|
|
|
=== Workflow activation and scheduling
|
|
|
|
When a workflow is triggered by an event, the engine logs the activation and scheduling of the first step:
|
|
|
|
* `Workflow '<name>' activated for resource <id> (execution id: <id>)` — the workflow execution has been created and is being processed.
|
|
* `Scheduled step <step> to run in <duration> for resource <id> (execution id: <id>)` — a scheduled step has been queued to run after the specified duration.
|
|
|
|
=== Step execution
|
|
|
|
As steps are executed, the engine logs their progress:
|
|
|
|
* `Running step <step> on resource <id> (execution id: <id>)` — a step is about to be executed.
|
|
* `Step <step> completed successfully (execution id: <id>)` — the step finished without errors.
|
|
* `Workflow '<name>' completed for resource <id> (execution id: <id>)` — all steps in the workflow have been executed.
|
|
|
|
=== Step failures and timeouts
|
|
|
|
When a step fails or the executor times out, the engine logs the error and fires a step failed event. The step will be
|
|
retried in the next execution cycle (see <<_handling_failures_>> for more details).
|
|
|
|
* `Step <step> failed (execution id: <id>) - error message: <message>` — the step threw an exception during execution.
|
|
* `Workflow executor timed out during execution of step <step>` — runtime exception indicating that the step exceeded the configured executor task timeout. See <<_understanding_workflows_engine_>> for how to configure the timeout.
|
|
* `Workflow executor was cancelled during execution of step <step>` — runtime exception indicating that the executor service was cancelled for a reason other than timeout.
|
|
|
|
=== Skipped and cancelled workflows
|
|
|
|
* `Skipping workflow <name> as it is disabled` — the workflow is disabled and will not process events.
|
|
* `Workflow '<name>' cancelled for resource <id> (execution id: <id>)` — the workflow execution was cancelled.
|
|
* `Resource <id> is no longer eligible for workflow <name>. Cancelling execution of the workflow.` — the resource no longer meets the workflow conditions upon resuming a scheduled step.
|
|
|
|
=== Workflow errors
|
|
|
|
* `Error processing event <event> for workflow <name>: <message>` — an error occurred while processing the event that triggers the workflow.
|
|
* `Error resuming workflow <name> for resource <id>: <message>` — an error occurred while resuming a scheduled workflow execution.
|
|
* `Could not find step <step> in workflow <name> for resource <id>. Cancelling execution of the workflow.` — the step scheduled to run could not be found in the workflow.
|
|
|
|
=== Step-level warnings
|
|
|
|
Individual step providers log warnings when configuration is missing or invalid. Examples include:
|
|
|
|
* `Missing required configuration option '<key>' in <step>` — a required parameter was not provided in the step's `with` block.
|
|
* `Invalid required action <action> configured in <step>` — the required action name is not recognized.
|
|
* `User <id> has no email address, skipping notification` — the `notify-user` step could not send an email.
|
|
* `Failed to send notification email to <recipient>` — an email delivery failure occurred.
|
|
|
|
== Useful log categories
|
|
|
|
If you need more targeted logging, you can enable debug logging for specific components:
|
|
|
|
[cols="2*", options="header"]
|
|
|===
|
|
|Category
|
|
|Description
|
|
| `org.keycloak.models.workflow` | All workflow-related logging (engine, steps, state)
|
|
| `org.keycloak.models.workflow.DefaultWorkflowProvider` | Workflow engine lifecycle (activation, conditions, event processing)
|
|
| `org.keycloak.models.workflow.RunWorkflowTask` | Step execution, completion, failures, and timeouts
|
|
| `org.keycloak.models.workflow.ScheduleWorkflowTask` | Step scheduling and delayed execution
|
|
|===
|