---
title: "Exceptions — Workflows for Laravel | Roundly"
description: "Every exception with its errorCode() and HTTP status — unknown definitions, conflicts, invalid graphs and inputs, authorization and registration errors."
url: https://roundly-consulting.com/open-source/docs/workflows-for-laravel/exceptions
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Workflows for Laravel](https://roundly-consulting.com/open-source/docs/workflows-for-laravel.md)

# Exceptions

Every domain exception extends WorkflowsException (a RuntimeException) with errorCode(): string, status(): int and context(): array — the code plus the definition key, node or instance where known, what Laravel’s logger adds to a report; never a payload or a secret. Messages are translated (en, sk) and name keys, node ids and basenames, never a PHP class:

| Exception | errorCode() | status() | Thrown when |
| --- | --- | --- | --- |
| `UnknownDefinitionException` | `unknown_definition` | 404 | No definition with the key in this scope (the message names the scope), or no webhook definition with that hook id. |
| `NoVersionException` | `no_version` | 404 | A dry run or export of a definition with no version yet, or a missing version number. |
| `SubjectOwnerMismatchException` | `subject_owner_mismatch` | 404 | The subject belongs to another owner (never confirms existence). |
| `DefinitionNotActiveException` | `definition_not_active` | 409 | A start of a retired definition. |
| `DefinitionKeyTakenException` | `definition_key_taken / definition_key_trashed` | 409 | The key is taken for this owner (also by a soft-deleted definition: restore it). |
| `DraftConflictException` | `draft_conflict` | 409 | edit() with a stale $expectedChecksum. |
| `NothingToPublishException` | `nothing_to_publish` | 409 | publish() without a draft. |
| `PublishedVersionImmutableException` | `published_version_immutable` | 409 | A write to a frozen column of a published version. |
| `TriggerMismatchException` | `trigger_mismatch` | 409 | A start path that doesn’t match the version’s trigger (start() on a non-manual definition). |
| `InstanceNotRetryableException` | `instance_not_retryable` | 409 | Retry of an instance that isn’t failed on a step. |
| `InstanceNotCancellableException` | `instance_not_cancellable` | 409 | Cancel of a terminal instance. |
| `InvalidGraphException` | `invalid_graph` | 422 | Publish (or a draft save) of an invalid graph; validationReport(); the message lists the first three problems. |
| `InvalidTriggerInputException` | `invalid_trigger_input` | 422 | Manual input fails validation; errors(). |
| `InvalidDefinitionException` | `invalid_definition_key / definition_needs_subject` | 422 | A key outside ^\[a-z0-9\]\[a-z0-9.\_-\]{0,99}$; a start without the subject the definition needs. |
| `InvalidEventKeyException` | `invalid_event_key` | 422 | An emitted key outside the pattern, or an internal @ key. |
| `InvalidTemplateException` | `invalid_template` | 422 | An import payload that isn’t a valid template. |
| `InvalidDiffException` | `invalid_diff` | 422 | A diff of versions of two different definitions. |
| `MissingIdempotencyKeyException` | `missing_idempotency_key` | 422 | A webhook start whose key source is empty. |
| `MissingTriggeringUserException` | `missing_triggering_user` | 422 | An on\_behalf\_of start without a user. |
| `SubjectTypeMismatchException` | `subject_type_mismatch` | 422 | A subject of another registered type than the definition’s. |
| `UnknownSubjectTypeException` | `unknown_subject_type / unregistered_subject_model` | 422 | An unknown subject type key (suggests the closest); a model with no registered type. |
| `UnknownStepTypeException` | `unknown_step_type` | 422 | An unknown step type (suggests the closest, or names the package a bridged type needs). |
| `UnknownCalendarException` | `unknown_calendar` | 422 | An unknown calendar (suggests the closest). |
| `BusinessCalendarNeverOpenException` | `calendar_never_open` | 422 | No open time within the search window. |
| `StepAuthorizationDeniedException` | `authorization_denied` | 403 | The authorization hook refused (the policy’s message, if any). |
| `DuplicateStepTypeException` | `duplicate_step_type` | 500 | Another class registers an existing step key. |
| `InvalidStepTypeException` | `invalid_step_key / unsupported_schema_keyword / invalid_schema_pattern / not_a_step_type` | 500 | A step type that can’t be registered. |

InvalidWorkflowsConfigurationException (every configuration error) extends the toolkit’s PackageToolkitException, not WorkflowsException: it is a programming error, not an HTTP answer. Handlers throw Steps\\StepFailedException (permanent) and Steps\\RetryableStepException (retried). Inside a step, any WorkflowsException fails the step permanently with its own error code.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/workflows-for-laravel.md)