Custom Error Pages in Symfony Framework

As I make my way through some tutorials on SymfonyCasts and begin a re-write of my SyntaxSeed website from CodeIgniter to Symfony… I occasionally encounter something that took a bit more struggle than a simple web search. This is one of those tasks.

Symfony gives you some generic built in error pages, for example when you get a 404 missing resource error or a 500 error. When working in your dev environment you don’t see these, you instead get the nice Whoops error pages with extra details. Customizing the error pages requires a few steps.

First off, I assume you are using Symfony version 5.1 or later and are using the Twig templating engine.

Begin by ensuring you have both Twig and the Twig-Pack installed in your project with Composer:

composer require twig
composer require symfony/twig-pack

Bonus Side Note…. while you’re at it you might want some nice extras in Twig including filters like truncate() or wordwrap. You can install these with:

composer require twig/string-extra
composer require twig/extra-bundle

And use them like so:

{{ summary|u.truncate(100, '...') }}

Anyway, where were we… oh yes… customising the error pages. Once you have the twig-pack installed you need to create a set of new files:

/templates/bundles/TwigBundle/Exception/
   - error404.html.twig
   - error500.html.twig
   - error.html.twig 

Create one for each error type you wish to customise and create error.html.twig as a fallback for all other error types.

Previewing Your Custom Symfony Error Pages

Ok so you’ve made a nice error page… how do you check it out? As you work on your project you’re probably in the dev environment (configured in your .env file). This means when you get errors you will probably see the helpful Symfony error page with the ghost in the upper right.

Your first option is to switch your environment in the .env file from dev to prod. Then make sure you clear your template cache:

php bin/console cache:clear --env=prod

Now if you visit a non-existing route, you should see your 404 page.

How do you preview these pages while still being in the dev environment? Symfony has a special route to do so:

https://127.0.0.1:8000/index.php/_error/404

Replace the code number on the end with the type of error you want to preview. Note that your local site might be using localhost instead of 127.0.0.1:8000. I believe this only works in the dev environment.

It’s Still Not Working!?

Ensure that you have cleared your cache a few times in the correct environment and that the path and filenames for your custom error pages are correct. Also have a look in your composer.json file and ensure you have the right composer packages installed. For me, I have (this is for a Symfony 5.2 project):

"symfony/twig-bundle": "5.2.*",
"twig/extra-bundle": "^3.3",
"twig/twig": "^2.12|^3.0"

To be honest, this process was a bit finicky for me. I had to re-install the twig-pack a couple times before it would work. I did not have to add any special config values, routes or service hooks or anything to get this to work. I re-installed the pack, removed any Twig code from my templates, clear the cache and it worked. I then added Twig code back into the template and it continued to work.

I hope this was helpful – thanks for reading!

Leave a Reply

Your email address will not be published. Required fields are marked *