Troubleshooting

Common Issues

Workflow not triggering

Symptom: Workflowable::dispatch() throws a WorkflowNotFoundException.

Causes:

• No active workflow is bound to the event name. Check is_active is true and event_name matches.
• The event class is not registered in config/workflowable.php under events.
• The event name in your config doesn't match the event_name column on the workflow.

Fix: Verify with php artisan workflowable:list --active and check the event binding.

Action handler not found

Symptom: StepExecutionException during execution.

Causes:

• Action handler not registered in config or via ActionRegistry.
• Typo in the handler name in the workflow definition.

Fix: Check config/workflowable.php and ensure the handler name matches exactly.

Workflow stuck in "in_progress"

Symptom: Instance never completes or fails.

Causes:

• An infinite loop in transitions (unlikely with max_steps limit).
• A queued job failed silently.
• A custom step type returned StepResult::waiting() and nothing resumed execution.

Fix:

1. Check php artisan workflowable:status {id} for the current step.
2. Check your queue worker logs.
3. Use php artisan workflowable:verify {id} to check state integrity.

Encrypted fields not decrypting

Symptom: Workflow variables contain encrypted strings instead of plain values.

Causes:

• The APP_KEY changed between encryption and decryption.
• The encrypted() method on the WorkflowEvent doesn't list the field.

Retry not working

Symptom: Step fails immediately without retrying.

Causes:

• No retry key on the step definition and no default_retry in config.
• max_attempts set to 0 or 1.

Fix: Add a retry block to the step or set execution.default_retry in config.

Exceptions

Exception	Cause
WorkflowNotFoundException	No active workflow found for the given name or event
WorkflowInstanceNotFoundException	Instance ID doesn't exist
StepExecutionException	Step handler threw an exception
InvalidWorkflowDefinitionException	Definition JSON is malformed or missing required fields
InvalidTransitionException	No valid transition for the step's result
StepTypeNotRegisteredException	Step type name not found in the registry

Debugging Tips

1. Check stored events: The stored events table contains a full audit trail of every action. Use $instance->storedEvents() to inspect.
2. Listen to events: Register listeners for StepFailed and WorkflowFailed to log errors.
3. Use workflowable:status: Inspect instance state from the CLI.
4. Use workflowable:verify: Replay stored events to verify state integrity. Use --fix to correct drift.
5. Check step executions: The step_executions table tracks each attempt with input, output, and error data.