Error Handling

• Introduction
• Configuration
• The Exception Handler
  • Reporting Exceptions
  • Ignoring Exceptions By Type
  • Rendering Exceptions
  • Reportable & Renderable Exceptions
  • Mapping Exceptions By Type
• HTTP Exceptions
  • Custom HTTP Error Pages

Introduction

When you start a new Laravel project, error and exception handling is already configured for you. The App\Exceptions\Handler class is where all exceptions thrown by your application are logged and then rendered to the user. We'll dive deeper into this class throughout this documentation.

Configuration

The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

During local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false. If the value is set to true in production, you risk exposing sensitive configuration values to your application's end users.

The Exception Handler

Reporting Exceptions

All exceptions are handled by the App\Exceptions\Handler class. This class contains a register method where you may register custom exception reporting and rendering callbacks. We'll examine each of these concepts in detail. Exception reporting is used to log exceptions or send them to an external service like Flare, Bugsnag or Sentry. By default, exceptions will be logged based on your logging configuration. However, you are free to log exceptions however you wish.

For example, if you need to report different types of exceptions in different ways, you may use the reportable method to register a closure that should be executed when an exception of a given type needs to be reported. Laravel will deduce what type of exception the closure reports by examining the type-hint of the closure:

 1use App\Exceptions\InvalidOrderException;
 2 
 3/**
 4 * Register the exception handling callbacks for the application.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->reportable(function (InvalidOrderException $e) {
11        //
12    });
13}
 1use App\Exceptions\InvalidOrderException;
 2 
 3/**
 4 * Register the exception handling callbacks for the application.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->reportable(function (InvalidOrderException $e) {
11        //
12    });
13}

When you register a custom exception reporting callback using the reportable method, Laravel will still log the exception using the default logging configuration for the application. If you wish to stop the propagation of the exception to the default logging stack, you may use the stop method when defining your reporting callback or return false from the callback:

1$this->reportable(function (InvalidOrderException $e) {
2    //
3})->stop();
4 
5$this->reportable(function (InvalidOrderException $e) {
6    return false;
7});
1$this->reportable(function (InvalidOrderException $e) {
2    //
3})->stop();
4 
5$this->reportable(function (InvalidOrderException $e) {
6    return false;
7});

Global Log Context

If available, Laravel automatically adds the current user's ID to every exception's log message as contextual data. You may define your own global contextual data by overriding the context method of your application's App\Exceptions\Handler class. This information will be included in every exception's log message written by your application:

 1/**
 2 * Get the default context variables for logging.
 3 *
 4 * @return array
 5 */
 6protected function context()
 7{
 8    return array_merge(parent::context(), [
 9        'foo' => 'bar',
10    ]);
11}
 1/**
 2 * Get the default context variables for logging.
 3 *
 4 * @return array
 5 */
 6protected function context()
 7{
 8    return array_merge(parent::context(), [
 9        'foo' => 'bar',
10    ]);
11}

Exception Log Context

While adding context to every log message can be useful, sometimes a particular exception may have unique context that you would like to include in your logs. By defining a context method on one of your application's custom exceptions, you may specify any data relevant to that exception that should be added to the exception's log entry:

 1<?php
 2 
 3namespace App\Exceptions;
 4 
 5use Exception;
 6 
 7class InvalidOrderException extends Exception
 8{
 9    // ...
10 
11    /**
12     * Get the exception's context information.
13     *
14     * @return array
15     */
16    public function context()
17    {
18        return ['order_id' => $this->orderId];
19    }
20}
 1<?php
 2 
 3namespace App\Exceptions;
 4 
 5use Exception;
 6 
 7class InvalidOrderException extends Exception
 8{
 9    // ...
10 
11    /**
12     * Get the exception's context information.
13     *
14     * @return array
15     */
16    public function context()
17    {
18        return ['order_id' => $this->orderId];
19    }
20}

The report Helper

Sometimes you may need to report an exception but continue handling the current request. The report helper function allows you to quickly report an exception via the exception handler without rendering an error page to the user:

 1public function isValid($value)
 2{
 3    try {
 4        // Validate the value...
 5    } catch (Throwable $e) {
 6        report($e);
 7 
 8        return false;
 9    }
10}
 1public function isValid($value)
 2{
 3    try {
 4        // Validate the value...
 5    } catch (Throwable $e) {
 6        report($e);
 7 
 8        return false;
 9    }
10}

Ignoring Exceptions By Type

When building your application, there will be some types of exceptions you simply want to ignore and never report. Your application's exception handler contains a $dontReport property which is initialized to an empty array. Any classes that you add to this property will never be reported; however, they may still have custom rendering logic:

 1use App\Exceptions\InvalidOrderException;
 2 
 3/**
 4 * A list of the exception types that should not be reported.
 5 *
 6 * @var array
 7 */
 8protected $dontReport = [
 9    InvalidOrderException::class,
10];
 1use App\Exceptions\InvalidOrderException;
 2 
 3/**
 4 * A list of the exception types that should not be reported.
 5 *
 6 * @var array
 7 */
 8protected $dontReport = [
 9    InvalidOrderException::class,
10];

Rendering Exceptions

By default, the Laravel exception handler will convert exceptions into an HTTP response for you. However, you are free to register a custom rendering closure for exceptions of a given type. You may accomplish this via the renderable method of your exception handler.

The closure passed to the renderable method should return an instance of Illuminate\Http\Response, which may be generated via the response helper. Laravel will deduce what type of exception the closure renders by examining the type-hint of the closure:

 1use App\Exceptions\InvalidOrderException;
 2 
 3/**
 4 * Register the exception handling callbacks for the application.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->renderable(function (InvalidOrderException $e, $request) {
11        return response()->view('errors.invalid-order', [], 500);
12    });
13}
 1use App\Exceptions\InvalidOrderException;
 2 
 3/**
 4 * Register the exception handling callbacks for the application.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->renderable(function (InvalidOrderException $e, $request) {
11        return response()->view('errors.invalid-order', [], 500);
12    });
13}

You may also use the renderable method to override the rendering behavior for built-in Laravel or Symfony exceptions such as NotFoundHttpException. If the closure given to the renderable method does not return a value, Laravel's default exception rendering will be utilized:

 1use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 2 
 3/**
 4 * Register the exception handling callbacks for the application.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->renderable(function (NotFoundHttpException $e, $request) {
11        if ($request->is('api/*')) {
12            return response()->json([
13                'message' => 'Record not found.'
14            ], 404);
15        }
16    });
17}
 1use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 2 
 3/**
 4 * Register the exception handling callbacks for the application.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->renderable(function (NotFoundHttpException $e, $request) {
11        if ($request->is('api/*')) {
12            return response()->json([
13                'message' => 'Record not found.'
14            ], 404);
15        }
16    });
17}

Reportable & Renderable Exceptions

Instead of type-checking exceptions in the exception handler's register method, you may define report and render methods directly on your custom exceptions. When these methods exist, they will be automatically called by the framework:

 1<?php
 2 
 3namespace App\Exceptions;
 4 
 5use Exception;
 6 
 7class InvalidOrderException extends Exception
 8{
 9    /**
10     * Report the exception.
11     *
12     * @return bool|null
13     */
14    public function report()
15    {
16        //
17    }
18 
19    /**
20     * Render the exception into an HTTP response.
21     *
22     * @param  \Illuminate\Http\Request  $request
23     * @return \Illuminate\Http\Response
24     */
25    public function render($request)
26    {
27        return response(...);
28    }
29}
 1<?php
 2 
 3namespace App\Exceptions;
 4 
 5use Exception;
 6 
 7class InvalidOrderException extends Exception
 8{
 9    /**
10     * Report the exception.
11     *
12     * @return bool|null
13     */
14    public function report()
15    {
16        //
17    }
18 
19    /**
20     * Render the exception into an HTTP response.
21     *
22     * @param  \Illuminate\Http\Request  $request
23     * @return \Illuminate\Http\Response
24     */
25    public function render($request)
26    {
27        return response(...);
28    }
29}

If your exception extends an exception that is already renderable, such as a built-in Laravel or Symfony exception, you may return false from the exception's render method to render the exception's default HTTP response:

 1/**
 2 * Render the exception into an HTTP response.
 3 *
 4 * @param  \Illuminate\Http\Request  $request
 5 * @return \Illuminate\Http\Response
 6 */
 7public function render($request)
 8{
 9    // Determine if the exception needs custom rendering...
10 
11    return false;
12}
 1/**
 2 * Render the exception into an HTTP response.
 3 *
 4 * @param  \Illuminate\Http\Request  $request
 5 * @return \Illuminate\Http\Response
 6 */
 7public function render($request)
 8{
 9    // Determine if the exception needs custom rendering...
10 
11    return false;
12}

If your exception contains custom reporting logic that is only necessary when certain conditions are met, you may need to instruct Laravel to sometimes report the exception using the default exception handling configuration. To accomplish this, you may return false from the exception's report method:

 1/**
 2 * Report the exception.
 3 *
 4 * @return bool|null
 5 */
 6public function report()
 7{
 8    // Determine if the exception needs custom reporting...
 9 
10    return false;
11}
 1/**
 2 * Report the exception.
 3 *
 4 * @return bool|null
 5 */
 6public function report()
 7{
 8    // Determine if the exception needs custom reporting...
 9 
10    return false;
11}

Mapping Exceptions By Type

Sometimes, third-party libraries used by your application may throw exceptions that you wish to make renderable, but are unable to do so because you do not have control over the definitions of third-party exceptions.

Thankfully, Laravel allows you to conveniently map these exceptions to other exception types that you manage within your application. To accomplish this, call the map method from your exception handler's register method:

 1use League\Flysystem\Exception;
 2use App\Exceptions\FilesystemException;
 3 
 4/**
 5 * Register the exception handling callbacks for the application.
 6 *
 7 * @return void
 8 */
 9public function register()
10{
11    $this->map(Exception::class, FilesystemException::class);
12}
 1use League\Flysystem\Exception;
 2use App\Exceptions\FilesystemException;
 3 
 4/**
 5 * Register the exception handling callbacks for the application.
 6 *
 7 * @return void
 8 */
 9public function register()
10{
11    $this->map(Exception::class, FilesystemException::class);
12}

If you would like more control over the creation of the target exception, you may pass a closure to the map method:

1use League\Flysystem\Exception;
2use App\Exceptions\FilesystemException;
3 
4$this->map(fn (Exception $e) => new FilesystemException($e));
1use League\Flysystem\Exception;
2use App\Exceptions\FilesystemException;
3 
4$this->map(fn (Exception $e) => new FilesystemException($e));

HTTP Exceptions

Some exceptions describe HTTP error codes from the server. For example, this may be a "page not found" error (404), an "unauthorized error" (401) or even a developer generated 500 error. In order to generate such a response from anywhere in your application, you may use the abort helper:

1abort(404);
1abort(404);

Custom HTTP Error Pages

Laravel makes it easy to display custom error pages for various HTTP status codes. For example, if you wish to customize the error page for 404 HTTP status codes, create a resources/views/errors/404.blade.php view template. This view will be rendered on all 404 errors generated by your application. The views within this directory should be named to match the HTTP status code they correspond to. The Symfony\Component\HttpKernel\Exception\HttpException instance raised by the abort function will be passed to the view as an $exception variable:

1<h2>{{ $exception->getMessage() }}</h2>
1<h2>{{ $exception->getMessage() }}</h2>

You may publish Laravel's default error page templates using the vendor:publish Artisan command. Once the templates have been published, you may customize them to your liking:

1php artisan vendor:publish --tag=laravel-errors
1php artisan vendor:publish --tag=laravel-errors