In Laravel, how do you raise a field-level validation error from service or domain code that has no validator rule for the check?

## The situation Validation rules check the **shape** of input before the business logic runs. Some failures only appear **during** the logic: - A login attempt: the email and password are well-formed, but the credentials do not match. - An import: the SKU was valid when checked, but another process claimed it before the insert. - A checkout: the coupon exists, but the service discovers it is used up. You want the user to see these the same way as ordinary field errors — next to the right field, or in the same JSON structure — without writing a custom exception and a custom renderer for each. ## ValidationException::withMessages() ```php throw ValidationException::withMessages([ 'coupon' => 'This coupon has already been used.', ]); ``` What it does, per the source: 1. Creates an empty validator (`Validator::make([], [])`). 2. For each key, wraps the value with `Arr::wrap()` so a string or a list both work, and adds every message to the validator's error bag under that key. 3. Returns a new `ValidationException` around that validator. Because it is an ordinary `ValidationException`: - The exception handler renders it the same way as a failed rule — redirect back with errors and old input, or a **422** JSON response when the request expects JSON. - It is not reported to the log, like other validation failures. - The exception message is a summary built from the first error, for example "This coupon has already been used." ## Adjusting the exception The exception has fluent setters: | Method | Effect | |---|---| | `->errorBag('checkout')` | put the errors in a named bag for pages with several forms | | `->redirectTo('/cart')` | redirect to a specific URL instead of back | | `->status(409)` | use a different status code for JSON responses than the default 422 | The default status is 422, held in the public `$status` property. ## Where to throw it - **Services called from controllers** — the natural fit; the controller stays free of error mapping. - **Actions or form-level logic** after validation passed. - **Not from queue jobs** that should report bad data as records; there is no user request to render the error to, so it only fails the job attempt. A reasonable pattern is to let domain code throw its own exception (`CouponExhausted`) and convert it at the boundary with `withMessages`, so the domain layer does not depend on HTTP-shaped errors. Throwing `withMessages` directly from a service is simpler and common in Laravel code; pick one convention per codebase. ## Versus the alternatives - `back()->withErrors(['coupon' => '...'])` from a controller does the redirect part manually but does nothing for JSON clients. - `abort(422, '...')` produces a generic HTTP error with no field key, so forms cannot attach it to a field. - A custom exception with its own `render()` works but has to recreate the error format that validation already provides. ## Common mistakes - Using a key that does not match the input name, so the view never shows the message next to the field. - Passing a nested array of arrays per key; each key takes a string or a flat list of strings. - Catching `ValidationException` around the service call and swallowing it, losing the message. ## Worked example: an import confirmation screen After uploading a CSV, the user confirms the import. The service re-checks that the file has not already been imported; if it has, it throws `ValidationException::withMessages(['file' => 'This file was already imported on 3 March.'])`. The browser returns to the confirmation form with the message under the file field, and an API client gets the same message in its 422 body — one line of code for both. ## Checklist - The key matches the input name the form or client uses. - The message is user-facing, not a stack-trace detail. - The throw happens in code that runs during an HTTP request, not in a worker. - A named bag is set when the page has several forms.