During development of your web application the debug mode (also called developer mode or developer environment) can be helpful for a variety of things. When enabled, the following things are in effect:
In Contao 4.4, the debug mode also bypasses the image cache of Contao. While
this can be useful, it will also slow down the page generation significantly on
pages with a lot of images. To disable bypassing of the image cache add the following
# app/config/config_dev.yml contao: image: bypass_cache: false
The way you activate the debug mode is different between Contao versions.
In Contao 4.4 you access the debug mode by accessing the
point. Prepend any URL you want to debug with that entry point. For example, if
you need to track down an error within the Contao Install Tool, then you would access
the debug mode via
app_dev.php entry point can be accessed at any time in your local developer
environment. However, in any other environment, you will need to set a username
and password first for security reasons.
Setting a username and a password for the
app_dev.php entry point can be done
the following via the
contao:install-web-dir console command:
$ vendor/bin/contao-console contao:install-web-dir --user=<USER> --password
<USER> with the desired username. The command line utility will then ask
you for the password. This creates a
.env file in the root directory of the Contao
installation containing an environment variable which in turn will contain the username
and the encrypted password.
In Contao 4.5 through 4.7 the username and password can also be set via the Contao Manager by using the Debug Mode option in the Maintenance section.
When clicking on Activate the Contao Manager will ask you for the username and
password for the
app_dev.php entry point. This in turn will execute the aforementioned
console command in the background and also create the
.env file accordingly.
In Contao 4.8 and up the debug mode is enabled either via a special cookie just for one user or via an environment variable for everyone.
The environment variable used for controlling the debug mode is called
and needs to be set to
dev in order to enable the debug mode. This environment
variable could be set globally in your system or within the configuration of your
web application’s web server. It is also possible to set this environment variable
.env files in your project root. The content of this files should then be:
It is also possible to create an (initially) empty
.env file and then next to
.env.local file with said content. Typically, you would then commit the
.env file to your project’s Git repository, but the
.env.local file should be
in your ignore list.
Do not deploy this file with the enabled debug mode to your live server! It would pose a major security risk.
Further environment variables can be set this way. A description can be found in the Developer Documentation.
The debug mode can also be enabled by administrators within the back end of Contao. Next to the preview button there will be a Debug Mode button. When clicked, this will set a special cookie that enables the debug mode only for the current user.
The button will only be displayed, if you have not defined the app environment in your
The debug mode can also be enabled from within the Contao Manager by using the Debug Mode option in the Maintenance section.
By clicking Activate the Contao Manager will also set a cookie enabling the debug mode for the current user. This cookie will only be valid for the currently active domain. In a multi domain setup, you will therefore need to start the Contao Manager under the domain, for which you want to enable the debug mode.
The Symfony Profiler and its toolbar give detailed information about the execution of any request. When the debug mode is enabled, the toolbar will appear at the bottom of the browser window in a fixed position. It can be collapsed and opened by clicking onto the Symfony logo.
Some of the information you can gather via the profiler are:
Usually when an error happens it will be logged into the
However, to track down the cause of the error it is often helpful to get the full
stack trace. Within the debug mode you will be able to reproduce
the error and then get the full stack trace in the browser window - as well as in