Using Debug Mode
The Flute CMS debug system helps quickly identify and resolve website errors. When problems occur (HTTP 500, white pages, unexpected behavior), debug mode provides detailed information about the causes of failures.
Debug mode should only be used during development or testing. On a production site, debug mode can reveal confidential information to visitors.
Enabling through Admin Panel
Full debug for all users
Go to Admin Panel → General Settings and activate the Debug Mode toggle. After saving the settings, debug information will be displayed for all site visitors.
Debug for specific IP addresses
For safe testing on a production site, use the IP address restriction feature. In the Debug IP addresses field, specify addresses separated by commas for which debug will be active.
To find out your IP address, use an IP detection service or check the Tracy Bar after enabling debug.
Examples of specifying IP addresses:
- Single address:
192.168.1.100 - Multiple addresses:
192.168.1.100, 10.0.0.5, 203.0.113.42
Enabling through configuration file
Direct configuration editing
If the admin panel is unavailable due to critical errors, debug can be enabled directly through the settings file.
Open the configs/app.php file in a text editor and find the line with the debug parameter. Change the value to true:
'debug' => true,
After resolving issues, be sure to return the debug value to false to ensure site security.
Analyzing error information
Critical errors
When serious problems occur, the debugger displays detailed information on the full screen:
- Error type — problem category (syntax, logical, system)
- Message — description of the specific problem
- File and line — exact location of the error in the code
- Call stack — sequence of function execution until the error occurred
- Variables — variable values at the time the error occurred
Tracy Bar — developer panel
Minor warnings and useful information are displayed in Tracy Bar — a special panel at the bottom of the page.
Tracy Bar contains many tabs with technical information. Studying this data will help you better understand system operation and optimize performance.
Practical debugging tips
Common causes of errors
Database errors — check connection settings in configs/database.php and database server availability.
Permission issues — ensure the web server has write permissions to storage, cache, and logs folders.
Plugin conflicts — temporarily disable recently installed extensions to identify the problematic component.
Memory shortage — increase PHP memory limit in server settings or .htaccess file.
Error logging
Flute CMS automatically saves error information to log files. You can find them in the storage/logs/ folder. These files are useful for analyzing problems that occurred earlier.
Cache clearing
If the site behaves strangely, try clearing the cache through the admin panel or by deleting the contents of the storage/app/cache/ folder.
Keep a log of changes on the site. This will help quickly determine after which actions the problem occurred.