Edit on GitHub
Jump to docs navigation

Debugging Bolt

Note: You are currently reading the documentation for Bolt 4.0. Looking for the documentation for Bolt 5.2 instead?

Configuring Bolt

When debugging in Bolt, often you'll need to adjust settings in your .env file.

Enabling debugging

Ensure you have debugging enabled:


Warning: When APP_DEBUG=1 is set, some internal data can be visible during debugging. You should therefore use caution with enabling debugging in a production environment.

Debug logging

The default application logger's messages are available in var/log/dev.log if in dev environment. In the production environment, the log is available in var/log/prod.log.

Note: This file's size can grow quickly.

Environment setting

When deploying a local Bolt site to the production environment, it is advised to set Bolt's environment variable to production. The environment variable is available in .env and can be set to


for production environments, or


when developing locally.

strict_variables: true


For debugging inside Twig templates themselves, see the dump and backtrace sections.

Of course the debug bar has profiling information available when hovering over the Twig profiler icon, or a listing of templates used, and a render call graph that can be useful to track down templates that are causing slow page rendering.


Symfony's debug Toolbar provides comprehensive information on:

  • Performance breakdown of the request/response cycle
  • Request & response object data
  • Exceptions & related trace data
  • Event dispatcher listeners that were, and were not, called
  • Database queries that were performed for the page load


For very basic debugging on PHP problems, Bolt has its own dump and backtrace functions available.


However, while more complex to set up, using xdebug in an IDE such as PhpStorm, Atom, VSCode, or Eclipse will make debugging PHP code so much simpler.

Also of worthy note, PhpStorm has the Symfony support plugin available, that makes getting PHPDoc information, code completion, and method parameter checking work for all parts of Bolt's code.

Likewise, for VSCode we can recommend the Intelephense extension. It is less extensive in scope as the PHP support you get with PhpStorm, but it makes a vast difference over "vanilla" VSCode.

Xdebug & Composer

If you are debugging Composer script use from the command line, be aware of two things:

  • Composer disables xdebug by default at runtime
  • Running Composer from composer.phar will not work with xdebug

To work around this run Composer from the vendor directory like so:

COMPOSER_ALLOW_XDEBUG=true vendor/bin/composer run-script {script name}

Other pages in this section:

Edit this page on GitHub
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.