PrestaShop Debug Mode — How to Enable & Use It [2026]

PrestaShop debug mode (_PS_MODE_DEV_) shows full PHP error messages instead of a white screen or a generic "Oops! An error occurred". It is the first tool of every diagnosis: without it, fixing a failure is guesswork. Enabling takes a minute — one parameter in config/defines.inc.php. Below: how to enable debug mode in PrestaShop 1.6, 1.7, 8 and 9, how to use it safely and how to read the messages. Failure diagnostics by a specialist: 500–1,500 PLN net with a report.

Key takeaway: You enable PrestaShop debug mode in config/defines.inc.php: set define('_PS_MODE_DEV_', true);. On production, do it only on a store copy — error messages visible to customers leak server information. In PrestaShop 1.7+/8/9 the PS_MODE_DEV environment variable (.env) also works. After the diagnosis, disable debug and clear the cache. Debug shows the full stack trace: file, line and error class — that is 90% of a failure diagnosis.

Why enable debug mode

By default PrestaShop hides PHP errors from users: instead of a message you get a white screen or a generic "Oops! An error occurred" screen. That looks "professional" but makes diagnosis impossible. Debug mode reverses this behaviour:

• it shows the full error message with file and line of code,
• it displays the stack trace — the call path leading to the error,
• it reveals warnings (Warning, Notice) that are hidden in production and often precede a more serious problem,
• in PrestaShop 8/9 it additionally switches the Symfony environment to dev (full logs in var/logs/dev.log).

As a result, instead of "the store is broken" you know exactly that, for example, module X calls a non-existent method on line 214 of its file.

How to enable debug mode — PrestaShop 1.7 / 8 / 9

1. Access the store files (FTP/SFTP/SSH) — preferably on a copy of the environment.
2. Open config/defines.inc.php.
3. Find the line define('_PS_MODE_DEV_', false); and change it to true.
4. Save the file and refresh the page where the error occurs.

In PrestaShop 8/9 you can also use the .env file in the root directory: set PS_MODE_DEV=true (and APP_ENV=dev if you want the full Symfony mode). This is more convenient because .env does not end up in the repository as easily as defines.inc.php.

After the change, clear the cache: panel → Advanced Parameters → Performance → Clear cache, or delete the contents of var/cache while keeping the directory structure.

How to enable debug mode — PrestaShop 1.6

In PrestaShop 1.6 the parameter is in config/defines.inc.php and has the same name: _PS_MODE_DEV_. Set it to true, save, refresh the page. You can additionally enable _PS_DEBUG_SQL_ (SQL query preview) — useful for database errors, but enable it only on a copy.

Reading error messages

A debug message has a fixed structure. Example

• **Fatal error:** Uncaught Error: Call to undefined method PaymentModule::validateOrder2() in /var/www/shop/modules/mymodule/mymodule.php on line 214

What you can read from it

• error type — Fatal error stops the page, Warning is a notice,
• class and method — PaymentModule::validateOrder2() — what is missing,
• file and line — /modules/mymodule/mymodule.php:214 — the guilty module,
• stack trace — the subsequent calls show how the store reached the error.

The most common messages and what they mean

• **| failed to open stream:** Permission denied | File permissions | Directories 755, files 644 | | SQLSTATE[...] | Database error | Check the table and query from the message | | Cannot redeclare | Override conflict | Look for a duplicate in override/ |

• ## Safety: debug only on a copy

Debug mode on production means every visitor can see server paths, fragments of configuration and SQL queries. That is an invitation for attackers. The rules:

• enable debug on a store copy (staging) — a full copy of files and database,
• if you must diagnose something on production, enable debug for a few minutes, during low traffic, and disable it immediately,
• after disabling debug, clear the cache — messages must not remain in cached pages,
• never leave _PS_MODE_DEV_ set to true after the work is done.

Warning: Debug mode on production exposes file paths, database table names and server configuration to customers. If you do not have an environment copy, make one first — diagnosing on a copy is the standard, not a luxury.

When you have no file access

Even without FTP/SSH access you can diagnose a failure

• ask your host to enable display_errors in PHP for a domain copy,
• read the PHP logs from the hosting panel (error_log, daily logs),
• check var/logs/ through the panel's file manager,
• ask hosting support for the latest PHP error entries from your account — hosts provide them as standard.

The logs contain the same information as the debug screen, just in file form — instructions for reading them are in PrestaShop logs.

Debug mode and other diagnostic tools

Debug mode is the foundation, but not the only tool

• logs — always work, including on production; they complement debug with history,
• _PS_DEBUG_PROFILING_ — SQL query and execution time profiling (PrestaShop 1.7+), useful for performance,
• _PS_DEBUG_SQL_ — SQL query preview, helpful for database errors,
• the browser developer console — JavaScript and network request errors (e.g. when the Parcel Locker map fails to load).

Enable profiling only on a copy — it can put a heavy load on the store.

Frequently asked questions

How do I enable debug mode in PrestaShop 8?

In config/defines.inc.php set define('_PS_MODE_DEV_', true); or in the .env file set PS_MODE_DEV=true. After the change, clear the cache (panel → Performance or deleting the contents of var/cache). Do this on a store copy — on production only briefly and during low traffic.

Does debug mode slow the store down?

Yes — debug disables part of the caching and adds overhead to every request, which is why it is not left enabled in production. For diagnosis this does not matter: you load one page and read the error. After the diagnosis, disable debug and clear the cache.

White screen even in debug mode — why?

A white screen with _PS_MODE_DEV_ enabled means a server-level error (PHP-FPM not starting, process memory limit, .htaccess error) or that debug was not actually enabled (configuration cache). Check the server logs — the cause will be there. Procedure: PrestaShop white screen.

Will debug mode show payment module errors?

Yes, every PHP error in a payment module will be displayed with file and line. Remember, however, that some payment problems are logic errors (webhooks, order statuses) that debug will not show — diagnosing them requires module logs. More: checkout not working.

Sources and tools

• PrestaShop DevDocs — development environment
• PrestaShop DevDocs — documentation
• PHP — error handling

👉 Cannot diagnose the failure yourself? Enable debug on a copy and send the message — contact form or kontakt@informatix.com.pl. See also PrestaShop technical help.

📖 See also: PrestaShop white screen, 500 error and PrestaShop logs.