Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Cookbook
  4. Controller
  5. How to Customize Error Pages
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • The default ExceptionController
  • Override Error Templates
  • Customizing the 404 Page and other Error Pages
  • Replace the default Exception Controller

How to Customize Error Pages

Edit this page

Warning: You are browsing the documentation for Symfony 2.4, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

How to Customize Error Pages

When any exception is thrown in Symfony, the exception is caught inside the Kernel class and eventually forwarded to a special controller, TwigBundle:Exception:show for handling. This controller, which lives inside the core TwigBundle, determines which error template to display and the status code that should be set for the given exception.

Error pages can be customized in two different ways, depending on how much control you need:

  1. Customize the error templates of the different error pages;
  2. Replace the default exception controller twig.controller.exception:showAction.

The default ExceptionController

The default ExceptionController will either display an exception or error page, depending on the setting of the kernel.debug flag. While exception pages give you a lot of helpful information during development, error pages are meant to be shown to the end-user.

Testing Error Pages during Development

You should not set kernel.debug to false in order to see your error pages during development. This will also stop Symfony from recompiling your twig templates, among other things.

The third-party WebfactoryExceptionsBundle provides a special test controller that allows you to display your custom error pages for arbitrary HTTP status codes even with kernel.debug set to true.

Override Error Templates

All of the error templates live inside the TwigBundle. To override the templates, simply rely on the standard method for overriding templates that live inside a bundle. For more information, see Creating and Using Templates.

For example, to override the default error template, create a new template located at app/Resources/TwigBundle/views/Exception/error.html.twig:

1
2
3
4
5
6
7
8
9
10
11
<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>An Error Occurred: {{ status_text }}</title>
</head>
<body>
    <h1>Oops! An Error Occurred</h1>
    <h2>The server returned a "{{ status_code }} {{ status_text }}".</h2>
</body>
</html>

Caution

You must not use is_granted in your error pages (or layout used by your error pages), because the router runs before the firewall. If the router throws an exception (for instance, when the route does not match), then using is_granted will throw a further exception. You can use is_granted safely by saying {% if app.user and is_granted('...') %}.

Tip

If you're not familiar with Twig, don't worry. Twig is a simple, powerful and optional templating engine that integrates with Symfony. For more information about Twig see Creating and Using Templates.

In addition to the standard HTML error page, Symfony provides a default error page for many of the most common response formats, including JSON (error.json.twig), XML (error.xml.twig) and even JavaScript (error.js.twig), to name a few. To override any of these templates, just create a new file with the same name in the app/Resources/TwigBundle/views/Exception directory. This is the standard way of overriding any template that lives inside a bundle.

Customizing the 404 Page and other Error Pages

You can also customize specific error templates according to the HTTP status code. For instance, create a app/Resources/TwigBundle/views/Exception/error404.html.twig template to display a special page for 404 (page not found) errors.

Symfony uses the following algorithm to determine which template to use:

  • First, it looks for a template for the given format and status code (like error404.json.twig);
  • If it does not exist, it looks for a template for the given format (like error.json.twig);
  • If it does not exist, it falls back to the HTML template (like error.html.twig).

Tip

To see the full list of default error templates, see the Resources/views/Exception directory of the TwigBundle. In a standard Symfony installation, the TwigBundle can be found at vendor/symfony/symfony/src/Symfony/Bundle/TwigBundle. Often, the easiest way to customize an error page is to copy it from the TwigBundle into app/Resources/TwigBundle/views/Exception and then modify it.

Note

The debug-friendly exception pages shown to the developer can even be customized in the same way by creating templates such as exception.html.twig for the standard HTML exception page or exception.json.twig for the JSON exception page.

Replace the default Exception Controller

If you need a little more flexibility beyond just overriding the template (e.g. you need to pass some additional variables into your template), then you can override the controller that renders the error page.

The default exception controller is registered as a service - the actual class is Symfony\Bundle\TwigBundle\Controller\ExceptionController.

To do this, create a new controller class and make it extend Symfony's default Symfony\Bundle\TwigBundle\Controller\ExceptionController class.

There are several methods you can override to customize different parts of how the error page is rendered. You could, for example, override the entire showAction or just the findTemplate method, which locates which template should be rendered.

To make Symfony use your exception controller instead of the default, set the twig.exception_controller option in app/config/config.yml.

Tip

The customization of exception handling is actually much more powerful than what's written here. An internal event, kernel.exception, is thrown which allows complete control over exception handling. For more information, see Internals.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:
Symfony Code Performance Profiling

Symfony Code Performance Profiling

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

Avatar of Benjamin Morel, a Symfony contributor

Thanks Benjamin Morel for being a Symfony contributor

6 commits • 12 lines changed

View all contributors that help us make Symfony

Become a Symfony contributor

Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

Learn how to contribute

Symfony™ is a trademark of Symfony SAS. All rights reserved.

  • What is Symfony?
    • Symfony at a Glance
    • Symfony Components
    • Case Studies
    • Symfony Releases
    • Security Policy
    • Logo & Screenshots
    • Trademark & Licenses
    • symfony1 Legacy
  • Learn Symfony
    • Symfony Docs
    • Symfony Book
    • Reference
    • Bundles
    • Best Practices
    • Training
    • eLearning Platform
    • Certification
  • Screencasts
    • Learn Symfony
    • Learn PHP
    • Learn JavaScript
    • Learn Drupal
    • Learn RESTful APIs
  • Community
    • SymfonyConnect
    • Support
    • How to be Involved
    • Code of Conduct
    • Events & Meetups
    • Projects using Symfony
    • Downloads Stats
    • Contributors
    • Backers
  • Blog
    • Events & Meetups
    • A week of symfony
    • Case studies
    • Cloud
    • Community
    • Conferences
    • Diversity
    • Documentation
    • Living on the edge
    • Releases
    • Security Advisories
    • SymfonyInsight
    • Twig
    • SensioLabs
  • Services
    • SensioLabs services
    • Train developers
    • Manage your project quality
    • Improve your project performance
    • Host Symfony projects
    Deployed on
Follow Symfony
Search by Algolia