You can use the built-in Twig error renderer to override the default error templates. Both the TwigBundle and TwigBridge need to be installed for this. Run this command to ensure both are installed:

1

$ composer require symfony/twig-pack

When the error page loads, TwigErrorRenderer is used to render a Twig template to show the user.

This renderer uses the HTTP status code and the following logic to determine the template filename:

1. Look for a template for the given status code (like error500.html.twig);
2. If the previous template doesn't exist, discard the status code and look for a generic error template (error.html.twig).

To override these templates, rely on the standard Symfony method for overriding templates that live inside a bundle and put them in the templates/bundles/TwigBundle/Exception/ directory.

A typical project that returns HTML pages might look like this:

1
2
3
4
5
6
7

templates/
└─ bundles/
   └─ TwigBundle/
      └─ Exception/
         ├─ error404.html.twig
         ├─ error403.html.twig
         └─ error.html.twig      # All other HTML errors (including 500)

To override the 404 error template for HTML pages, create a new error404.html.twig template located at templates/bundles/TwigBundle/Exception/:

1
2
3
4
5
6
7
8
9
10
11

{# templates/bundles/TwigBundle/Exception/error404.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Page not found</h1>

    <p>
        The requested page couldn't be located. Checkout for any URL
        misspelling or <a href="{{ path('homepage') }}">return to the homepage</a>.
    </p>
{% endblock %}

In case you need them, the TwigErrorRenderer passes some information to the error template via the status_code and status_text variables that store the HTTP status code and message respectively.

Additionally you have access to the HttpException object via the exception Twig variable. For example, if the exception sets a message (e.g. using throw $this->createNotFoundException('The product does not exist')), use {{ exception.message }} to print that message. You can also output the stack trace using {{ exception.traceAsString }}, but don't do that for end users because the trace contains sensitive data.

Due to the order of how routing and security are loaded, security information will not be available on your 404 pages. This means that it will appear as if your user is logged out on the 404 page (it will work while testing, but not on production).

1
2
3
4
5
6

# config/routes/framework.yaml
when@dev:
    _errors:
        resource: '@FrameworkBundle/Resources/config/routing/errors.php'
        type:     php
        prefix:   /_error

1
2
3
4
5
6
7
8
9
10

// config/routes/framework.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    if ('dev' === $routes->env()) {
        $routes->import('@FrameworkBundle/Resources/config/routing/errors.php', 'php')
            ->prefix('/_error')
        ;
    }
};

To override non-HTML error output, the Serializer component needs to be installed.

1

$ composer require symfony/serializer-pack

The Serializer component has a built-in FlattenException normalizer (ProblemNormalizer) and JSON/XML/CSV/YAML encoders. When your application throws an exception, Symfony can output it in one of those formats. If you want to change the output contents, create a new Normalizer that supports the FlattenException input:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# src/Serializer/MyCustomProblemNormalizer.php
namespace App\Serializer;

use Symfony\Component\ErrorHandler\Exception\FlattenException;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

class MyCustomProblemNormalizer implements NormalizerInterface
{
    public function normalize($exception, ?string $format = null, array $context = []): array
    {
        return [
            'content' => 'This is my custom problem normalizer.',
            'exception'=> [
                'message' => $exception->getMessage(),
                'code' => $exception->getStatusCode(),
            ],
        ];
    }

    public function supportsNormalization($data, ?string $format = null, array $context = []): bool
    {
        return $data instanceof FlattenException;
    }
}

If you need a little more flexibility beyond just overriding the template, then you can change the controller that renders the error page. For example, you might need to pass some additional variables into your template.

To do this, create a new controller anywhere in your application and set the framework.error_controller configuration option to point to it:

1
2
3

# config/packages/framework.yaml
framework:
    error_controller: App\Controller\ErrorController::show

1
2
3
4
5
6
7
8
9
10
11
12

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <framework:config>
        <framework:error-controller>App\Controller\ErrorController::show</framework:error-controller>
    </framework:config>

</container>

The ErrorListener class used by the FrameworkBundle as a listener of the kernel.exception event creates the request that will be dised to your controller. In addition, your controller will be passed two parameters:

exception

The original Throwable instance being handled.

logger

A DebugLoggerInterface instance which may be null in some circumstances.

When an exception is thrown, the HttpKernel class catches it and dises a kernel.exception event. This gives you the power to convert the exception into a Response in a few different ways.

Working with this event is actually much more powerful than what has been explained before, but also requires a thorough understanding of Symfony internals. Suppose that your code throws specialized exceptions with a particular meaning to your application domain.

Writing your own event listener for the kernel.exception event allows you to have a closer look at the exception and take different actions depending on it. Those actions might include logging the exception, redirecting the user to another page or rendering specialized error pages.

This approach allows you to create centralized and layered error handling: instead of catching (and handling) the same exceptions in various controllers time and again, you can have just one (or several) listeners deal with them.

If an error occurs before reaching your Symfony application, web servers display their own default error pages instead of your custom ones. Dumping your application's error pages to static HTML ensures users always see your defined pages and improves performance by allowing the server to deliver errors instantly without calling your application.

Symfony provides the following command to turn your error pages into static HTML files:

1
2
3
4
5
6

# the first argument is the path where the HTML files are stored
$ APP_ENV=prod php bin/console error:dump var/cache/prod/error_pages/

# by default, it generates the pages of all 4xx and 5xx errors, but you can
# pass a list of HTTP status codes to only generate those
$ APP_ENV=prod php bin/console error:dump var/cache/prod/error_pages/ 401 403 404 500

You must also configure your web server to use these generated pages. For example, if you use Nginx:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# /etc/nginx/conf.d/example.com.conf
server {
    # Existing server configuration
    # ...

    # Serve static error pages
    error_page 400 /error_pages/400.html;
    error_page 401 /error_pages/401.html;
    # ...
    error_page 510 /error_pages/510.html;
    error_page 511 /error_pages/511.html;

    location ^~ /error_pages/ {
        root /path/to/your/symfony/var/cache/error_pages;
        internal; # prevent direct URL access
    }
}