Edit on GitHub
Jump to docs navigation

Debugging Bolt

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


Configuring Bolt

When debugging in Bolt, often you'll need to adjust settings in your app/config/config.yml file.

Enabling debugging

Ensure you have debugging enabled:

debug: true

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

Setting debug error level

It is also advised to set the debug error level to show all errors:

debug_error_level: -1

Enabling debug logging

Enabling the debug log writes the default application logger's messages to app/cache/bolt-debug.log.

    enabled: true

Note: This file's size can grow quickly.

Enabling debugging while logged off

If you're debugging problems on a development server, and are missing a login token, the debug bar, and dumping functions will not appear.

Setting debug_show_loggedoff will enable the debug bar, and dump output always.

debug_show_loggedoff: true

Warning: This should only be enabled in non-production environments.


When writing and debugging Twig templates in Bolt, enable strict_variables in your app/config/config.yml file, making Twig be strict on the use of undeclared variables.

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.


The debug bar 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 Silex Pimple plugin available, that makes getting PHPDoc information, code completion, and method parameter checking all work for keys on $app.

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.