PrestaShop Troubleshooting: Blank Pages, Errors and Recovery

What we would do

We would choose the recovery route from the shop you actually run: its exact PrestaShop and PHP releases, modules, theme overrides, catalogue and order data, integrations and hosting. Your languages, currencies, customer groups and team's access also affect what can be reproduced and safely changed. A module defect needs its maintainer; an installation or configuration problem needs a checked setup; a server failure needs the host or infrastructure owner.

For a code, module, theme or runtime change, use a private staging copy with the relevant live configuration, isolated from real payments, customer emails and fulfilment exports. Reproduce the fault, rehearse a reversible fix and agree the evidence required to reopen. Apply the tested change in a planned live window, with saved settings, matching packages and a named person able to reverse it. If immediate containment is needed, protect the affected journey first and keep the diagnostic changes narrow.

For the agreed installation and configuration of one existing module, the PrestaShop Module Installation & Configuration Service covers its settings and journey verification, with licences and development separate; it is not a general emergency-recovery service.

Choose your first route

If you find an unexplained administrator, altered payment destination or unexpected executable file, preserve the evidence and involve whoever handles security incidents. Ordinary module isolation is not enough to establish that the shop is safe to reopen.

Capture the failure and protect the current state

1. Stop unrelated installs, updates, imports and repeated cache clearing.
2. Record the exact time, timezone, URL or admin action, HTTP status, response text and browser error. Note who is affected.
3. List the last changes to core, modules, theme, PHP, hosting, proxy rules or scheduled jobs.
4. Preserve logs and take a file and database backup before recovery changes. Keep a pre-incident backup separately.
5. Restrict public traffic or use maintenance mode when the fault affects checkout, data integrity or public error output.
6. Reproduce on staging where possible, isolate one cause, test and record the result.

A blank body is a symptom, not proof of a PHP fatal. Empty output, early termination, a proxy response or an upstream failure can also produce it. Check the actual status and body in browser developer tools. An “AJAX error” needs the failed Network request and its response, not just the message shown by the interface.

After any meaningful fix, check homepage, category, product, cart, checkout and admin login. On staging, use payment sandbox mode and verify order totals, stock and confirmation output. Before reopening live checkout, confirm the production credentials, provider mode and callback endpoint, and agree a controlled live payment check where appropriate. Test the original failing action too.

Find the right log and read the whole error

Advanced Parameters > Logs contains events recorded by PrestaShop's database logger, subject to severity filtering. It is not a complete record of PHP, Symfony or bootstrap failures.

Do not change var/logs/ to var/log/ simply because the shop runs PrestaShop 8 or 9. Do not assume every environment uses exactly prod.log or dev.log. A CLI PHP configuration can also point to a different log from web PHP.

# From the shop root, inspect available application logs.
ls -lt var/logs/
# Follow the configured file after confirming its name.
tail -n 100 -f var/logs/prod.log

Correlate entries with the request time, environment and request identifier where present. Read the exception message, file, line and relevant stack frames. A frame in a module or theme is a lead, not proof that it is the root cause; bad input or an upstream dependency can fail there.

If no matching error appears, verify logging configuration, write access, rotation and available space. PHP error display and logging are separately configurable, so hidden output does not guarantee a log was written. Redact credentials, tokens and personal data before sharing logs.

Join the browser, proxy and application evidence

Treat each redirect and background request as a separate request. A working product page can still contain a failing stock, cart or configuration request. Where the infrastructure already supplies a request identifier, carry it through the support report; otherwise use the timestamp, method and exact path to correlate the records. Allow for different log timezones and a delayed job running after the browser response.

If the edge records an error but the origin has no matching request, inspect the proxy or hosting path before editing PHP. If the origin records a successful response but the browser receives different content, investigate intervening caching or response rewriting. Neither observation alone identifies the faulty component.

Use debug mode and profiling for different tasks

Use Advanced Parameters > Performance > Debug mode where available. The core switch is _PS_MODE_DEV_ in config/defines.inc.php. Change its existing declaration for a protected diagnostic session, then restore it:

define('_PS_MODE_DEV_', true);
// Restore production mode after collecting the error:
define('_PS_MODE_DEV_', false);

These are alternative states, not two declarations to paste together. Debug mode affects error display and application environment selection. It does not universally disable Smarty caching. The default debug mask excludes compatibility deprecations unless the compatibility-warning setting is enabled.

Use PrestaShop's controls rather than assuming generic APP_ENV or APP_DEBUG variables replace them. The application kernel uses PrestaShop environment and debug constants. Runtime ini_set() calls do not bypass later core configuration and cannot reveal a parse error that prevents that same entry script from running. Diagnose startup failures through PHP/server configuration and logs.

The Symfony profiler is available only for eligible Symfony requests when configured. It is not automatically attached to every storefront, legacy, AJAX or failing request. The separate legacy timing and query profiler uses _PS_DEBUG_PROFILING_ in config/defines.inc.php. Enable profiling briefly on protected staging and compare representative requests.

Public debug output can expose paths, SQL, tokens and sensitive configuration. Turn it off once you have captured the failure. For payment callbacks, prefer server logging over displaying exceptions.

Performance Revolution can issue an employee debug cookie after authenticating a back-office employee; its early bootstrap accepts possession of that token, and the refreshed four-hour browser expiry is not a server-side session or inactivity check. Treat it as a debug credential and use the module help page for setup and revocation.

Diagnose blank pages and HTTP errors by status

Use syntax checks for recently edited PHP files. For example:

php -l config/defines.inc.php
php -v
php --ini

Use the PHP binary intended for the shop. CLI success does not prove the web runtime has the same version, extensions, permissions or configuration.

Rewrites and .htaccess

On Apache, inspect the exact failing directive and whether the virtual host permits the required rewrite rules. Unsupported Options or php_value directives can cause errors. On Nginx, .htaccess is not read; review the server configuration instead.

Keep a copy before changing .htaccess. If you temporarily isolate it, do so under controlled access because it may also contain security rules. Saving Set up URLs under Shop Parameters > Traffic & SEO regenerates .htaccess when permissions allow. Robots.txt generation is a separate action.

Check ownership and the actual PHP execution user before changing permissions. Grant only the directory-specific write access the shop needs, including relevant cache, logs, images, uploads or module-generated files. A universal recursive chmod recipe can remove required access or expose files.

Isolate module conflicts and missing storefront output

On staging, test the most recent change first. If several modules interact, compare both enabled, each alone and neither. For larger sets, narrow controlled groups and retest dependencies. The last module enabled may expose an interaction without being solely responsible.

Prefer Module Manager's Disable action. A working console can use the supported module command; inspect help before selecting the technical module name and shop context:

php bin/console help prestashop:module

The command supports actions including disable, enable, install, upgrade and uninstall. Those actions have different effects. Changing only module.active in SQL does not reproduce normal disabling, which also handles shop associations and module behaviour. Avoid a blanket update of every third-party module row.

If neither admin nor console boots, temporarily moving the suspected module directory out of the module scan path can isolate files. Record its exact original location, preserve it privately and plan how to restore it. This does not remove installed overrides, reverse migrations or guarantee recovery from compiled-service references.

For override diagnosis, use Disable all overrides under Performance, backed by PS_DISABLE_OVERRIDES, and regenerate the class index. _PS_ALLOW_OVERRIDES_ and _PS_DISABLE_OVERRIDES_ are not the correct switches. A manual directory move also needs index handling.

Core can combine distinct override methods in one class, but overlapping methods or properties can conflict explicitly. Coordinate a compatibility patch with one owner and an installation/update plan. Do not assume pasting two implementations together will let both installers succeed.

If an installed display module produces nothing, check configuration, active shop, page/product scope and whether the theme renders a supported hook. In Design > Positions, review supported placements and order. Do not transplant a module to an arbitrary hook it does not implement. Then inspect template copies, browser errors and caches.

Separate a defect from unfinished configuration

Compare the failing setup with the installed release's instructions: required account settings, shop associations, hooks and completed migrations. An API credential rejected by the provider is a different support case from an exception with valid credentials. Give the maintainer a minimal reproduction on a supported configuration, and record any custom code needed to trigger it. Reinstalling or uninstalling as a diagnostic shortcut can remove configuration or data and make that comparison harder.

Clear the cache that matches the change and check autoloading

The back-office Clear cache action invokes a broader cache-clearer chain, not only Smarty. It still does not guarantee clearing every host, proxy, module or browser cache.

Prefer the back-office action or a coordinated console clear from the shop root:

php bin/console cache:clear --env=prod

Use the correct PHP binary and filesystem owner. If a broken bootstrap requires filesystem recovery, stop incoming traffic and workers, preserve logs, confirm the exact generated-cache paths and rebuild with correct ownership. Cache deletion is not inherently forbidden on PrestaShop 9; uncoordinated requests and failed rebuilds create the risk. Do not delete application files or undocumented module data as “cache”.

A CLI opcache_reset() does not reset an independent web OPcache pool. Use your host's controlled FPM or Apache reload/invalidation process as appropriate. Do not leave a public reset endpoint on the shop.

Class or namespace not found

1. Record the exact missing class and expected namespace.
2. Check that the complete release package is present, including a module's vendor/autoload.php and dependency files when supplied.
3. Check filename and namespace case on a case-sensitive filesystem, read access and the package's PHP requirements.
4. Restore a clean package rather than mixing files from different releases. Preserve documented uploads or exports separately.
5. Rebuild the relevant container and class index, then coordinate web OPcache.

Run Composer autoload generation only as part of the appropriate source/deployment workflow with the correct dependencies and lockfile. It does not recreate missing libraries. A class-index rebuild does not fix a missing namespaced Composer dependency. Avoid deleting module or hook database rows merely because a class is missing.

Fix memory exhaustion and incomplete form saves

Allowed memory size exhausted means a request exceeded its effective PHP memory limit. The fatal's final allocation site is not automatically the source of the growth. Large imports, image dimensions, combination-heavy forms, full-table reads, recursion and large object logging can all contribute.

Check the web value under Information where exposed and in the active FPM configuration. Estimate available RAM and worker concurrency before raising limits. For example, memory_limit = 512M can be a suitable setting for a workload, but it is not a guaranteed fix or a threshold every page must use.

Reduce oversized imports in controlled batches, process images separately where supported and profile unbounded results. A recurring failure does not prove a leak. Keep required integrations active unless you have tested the consequences of disabling them.

Settings or products save only partially

1. Open browser Console and Network. Check whether a POST was sent, its size, response and redirect.
2. Reopen the configuration screen from a fresh admin link to get a current token. Exclude the back office from public caching.
3. Verify employee configure permissions and the current shop context.
4. Check PHP input/body limits and any proxy or web-server limits.
5. Check a matching WAF rule rather than disabling the firewall broadly.
6. Inspect required module tables, completed migrations and documented writable paths.

max_input_vars limits parsed input variables. Exceeding it truncates input and issues E_WARNING; that warning may not appear in the back office. Many combinations and languages can create a large form, but they are not proof that this limit is the cause. Obtain the effective web value through hosting configuration or a protected diagnostic; not every Information page lists it.

Configure the limit before request parsing. Raising it inside the form handler is too late. A measured example for a large form might be:

max_input_vars = 5000
post_max_size = 64M
upload_max_filesize = 48M
max_execution_time = 300
memory_limit = 512M

These are example limits, not universal requirements. Keep POST capacity above an allowed upload plus overhead, and allow time for extraction or processing. Use php.ini, a supported .user.ini, FPM configuration or your hosting panel; Apache mod_php directives are not a general FPM solution. Confirm the effective values after the host's reload or configuration-cache delay.

For very large combination sets, consider native CSV import or the Webservice as alternatives to a huge form. Their parsing and resource constraints differ; they still have upload, body, execution and memory limits. See PHP's input-limit documentation.

Worked example: a large product loses translated fields

Suppose a small product saves, but a product with many combinations and languages loses values when reopened. That pattern suggests a size or field-count boundary, but the request evidence must distinguish it from application validation, a rejected request or a later write.

1. Keep a copy of the intended values and reproduce with the same product on staging. Compare a successful small submission with the failing one.
2. Check whether the missing fields were present in the browser's submitted payload. If they were absent, inspect the form and JavaScript before raising server limits.
3. If the fields were sent, inspect the request's Content-Type, response and matching PHP warning or application error. PHP's max_input_vars limits automatically parsed form variables; it does not limit keys decoded from a JSON body by application code. Use the effective web configuration to test the specific input or body limit implicated by the evidence.
4. After the change, reopen the product in the same shop and language, then another affected language. Confirm that existing combinations and unrelated fields survived.

If the values save correctly and later revert, correlate the later write with imports, scheduled synchronisation and other employees' edits. Increasing a parsing limit cannot prevent an integration from overwriting a previously successful save.

Match PHP to the exact PrestaShop release

Check web and CLI PHP separately. Confirm required extensions and every important module, dependency, theme and override before changing the runtime. Syntax linting is useful but cannot prove runtime compatibility.

These application compatibility ranges are not a statement that old PHP branches still receive security support. Consult the historical matrix, PrestaShop 8 matrix and PrestaShop 9 matrix for the exact release you use. Check 9.2's own requirements and dependencies rather than assuming an older 9.x test covers it.

For PHP errors, read the exact feature and version. In coercive mode, passing null to a non-nullable scalar parameter of many internal functions became deprecated in PHP 8.1; strict typing and other argument errors have different behaviour. See the implemented PHP RFC. Dynamic-property creation was deprecated in PHP 8.2, with exceptions. Deprecations do not universally become fatal in the next release; update the code according to each feature's migration schedule.

Investigate database errors and failed core updates

After an update failure, preserve the Update Assistant report and logs. Confirm the exact source and target versions, file completion, dependencies, PHP runtime and migration state. Do not assume that replacing files completed the database upgrade.

For “Unknown column”, inspect the actual table definition and the migration that should have produced it. Compare against a clean installation of the same target version while accounting for your prefix, modules and shop history. Do not paste a guessed ALTER statement or assume one historical install-dev/upgrade/sql/ directory is the current migration source.

SHOW CREATE TABLE ps_product;
SHOW FULL PROCESSLIST;
SHOW ENGINE INNODB STATUS;

These are diagnostic examples using ps_; use your real prefix and appropriate database permissions. Identify the blocking transaction, caller and business operation before cancelling a query. Schema changes and large rebuilds can lock or load the shop and need a planned window.

“Duplicate entry for key” means a unique constraint was violated. Identify the named index and actual value. Do not assume product references are unique or that re-running an installer will repair a partially completed migration.

For suspected corruption, preserve backups and inspect the engine's error logs. MyISAM repair commands are not general InnoDB recovery commands. Rebuilding a table with ALTER TABLE ... ENGINE=InnoDB is not a reliable physical-corruption remedy. Use an engine-specific recovery and dump/restore process; MySQL's InnoDB recovery guidance describes emergency recovery controls.

If the post-update code and schema cannot be reconciled safely, restore matching files and database from the pre-update backup under controlled access. Account for orders, payments and stock changes since that backup before overwriting live state.

Check templates, child themes and missing assets

When a template cannot load, check the requested module path, the module's shipped template and any theme copy under themes/your-theme/modules/. Theme template overrides can mask a newer module template. File and directory case matters on Linux.

For Smarty compilation errors, inspect the named source template, balanced {if} and {foreach} blocks, and any conflicting delimiters. JavaScript object literals do not all require a literal block: Smarty 3 handles delimiters surrounded by whitespace in the documented cases. Use escaping or {literal} only where needed, remembering that template expressions inside a literal block are not evaluated. See the Smarty documentation.

Check encoding and unintended output, including a BOM, without assuming every BOM causes a compiler failure. For asset errors, inspect the actual Network URL, status, response type and console message. Review theme configuration, registered assets, CCC output, deployment versioning and the CDN origin path.

A child theme requires its parent and compatible configuration. Compare overridden templates with the updated parent or module version. On staging, a known compatible default theme can help isolate the problem, but switching themes is a real configuration change and should be recorded and reversed after the test.

See child themes for the maintenance workflow.

Resolve login loops, tokens and lost carts

In browser Storage or Application tools, check cookie domain, path, Secure, HttpOnly, SameSite and size. Inspect rejected-cookie messages and the actual redirect chain. Compare the canonical host, shop_url records, SSL settings and proxy forwarding configuration. Do not alternate www and non-www or HTTP and HTTPS during checkout.

1. Try a clean browser profile or private window to isolate stored state.
2. Verify that admin responses and authenticated content bypass public caching.
3. Check cookie scope and whether the browser sends it on the failing request.
4. Confirm that a deployment did not unintentionally replace the expected cookie/encryption keys.
5. On multiple application nodes, check compatible keys and the session storage used by each relevant component.
6. Retest the full login or payment-return flow, including cross-site POST or 3-D Secure steps.

Do not change SameSite globally to None as a guess. Some cross-site flows need a different policy, with Secure required for None in modern browsers, but first identify which cookie and request lose state. The current core also limits the combined cookie name/value size to 4096 bytes; avoid putting large arrays or debug data into it.

An invalid-token error can come from expired state, an old form, changed host, blocked cookies, proxy behaviour or other request mismatches. Reopen the page through a current admin link and inspect the request. Increasing session.gc_maxlifetime is not a universal fix.

Cookies strictly necessary for the requested cart or authentication service can have different consent treatment from analytics or advertising. Assess the actual purpose, and verify that your consent integration controls nonessential tags. See sessions and cookies and GDPR and consent.

Check email delivery and server health separately

Email

Use Advanced Parameters > Email to send a controlled test, then check the configured SMTP endpoint, credentials, encryption and provider events. A row in the mail log is not proof of inbox delivery. Trace acceptance, rejection, bounce and spam placement separately.

Check sender-domain authentication and alignment through SPF, DKIM and DMARC with your mail provider. Do not assume that a chosen port or a move from local mail to SMTP guarantees delivery. If one order email fails, verify its template, language, recipient, triggering event and queue or module path before resending it. See email deliverability.

Sudden slowness

Measure server response time separately from slow browser assets. Check free bytes, free inodes, memory, load, database waits, PHP worker saturation and scheduled jobs:

df -h
df -i
uptime
free -m

There is no universal disk percentage at which a shop fails. Logs, temporary files, database writes and cache rebuilds need enough actual space. A storage failure can also prevent the diagnostic log from being written.

Check whether debug or profiling was left enabled. Profile costly queries and hooks under controlled conditions. Investigate overlapping import or cron jobs, locks, unbounded queries and growing connection, log, cart or guest data. Apply a retention policy before cleanup; preserve required orders and records.

Do not treat a cache module as a remedy for every 500 or 503. Follow the performance guide once the request and server bottleneck are identified.

Worked example: payment completes but checkout appears to fail

A customer reports a charge after the checkout spinner stops, but staff cannot find an order. First establish whether the provider shows an authorisation, a captured payment or a failed attempt. A customer screenshot and a checkout error do not establish the final financial state.

1. Keep the cart reference, payment reference, account and test/live mode, amount, currency and time. Search for any order created from that cart, including a delayed or split result.
2. Inspect the failed browser request separately from the provider's notification delivery and application processing. A notification blocked by maintenance or an access challenge needs a different fix from a handler that receives it and fails during order creation.
3. Use the integration's supported reconciliation or replay procedure after confirming the provider state. Have its maintainer check whether retrying can duplicate an order, payment, email or stock movement.
4. Rehearse the failing path on staging with provider test tools, including a customer who closes the browser before returning. Confirm the resulting order, transaction reference and downstream fulfilment state.

Do not tell the customer to pay again or manually mark an order paid while the original attempt is unresolved. Coordinate with whoever runs warehouse or ERP exports so that a delayed recovery does not release the same purchase twice. A browser-side repair does not by itself prove that the server-side payment workflow recovered.

Recover access, restore deliberately and verify the shop

Use the normal employee password-reset flow first. If email recovery is unavailable, have a developer use the installed version's hashing service in a private CLI recovery procedure for the exact employee. Modern PrestaShop uses its Hashing service; legacy 1.6 uses its older cookie-key-based mechanism. Do not leave an unauthenticated public password-reset script or a fixed password in the web root.

If admin access is lost, control traffic at the host or proxy while repairing it. Maintenance mode normally lives under Shop Parameters > General > Maintenance. Any emergency configuration change must use the actual prefix and shop scope, preserving old values and whitelist settings. A blanket update of every PS_SHOP_ENABLE row can affect other shops.

1. Choose matching files and database from a known recovery point. Preserve the failed state for investigation.
2. Stop public writes and jobs, then restore or apply the narrowly defined fix.
3. Reconcile transactions made after the recovery point, including payment-provider records.
4. Rebuild only the relevant caches with correct ownership and coordinate web OPcache and external caches.
5. Test the original symptom, admin access, catalogue, cart, sandbox checkout, emails and background jobs.
6. Check a clean browser and a second browser. Confirm that debug output and temporary tools are removed.
7. Record the root cause, files/settings changed, recovery point and test results before reopening fully.

Keep monitoring error logs, uptime, free storage and failed jobs after recovery. Test backups by restoring to staging. For an MPR support request, send the exact versions, timestamp, reproduction steps, affected scope, recent changes and redacted logs through contact support. Include the failed Network response for save or AJAX issues.

Move the tested fix back without replacing newer business data

Keep a change record that names the package or files, configuration values, migrations and cache actions needed for the fix. Deploy that defined change rather than copying the whole staging shop back over live. A staging database taken before today's orders is not a current replacement for the live database.

Before the live window, agree what would trigger reversal and whether the change wrote data that older code cannot read. Replacing files alone may not reverse a migration or an external API action. Keep incoming integrations and queued work under control, then reconcile held events before normal processing resumes. Use the backup and recovery guide when the chosen route requires a full restore.

What to ask your developer or agency

• What evidence identifies the cause, and which observations would rule it out? Ask for the failing request and matching error rather than a list of settings changed.
• Which parts of the live environment were reproduced, and which differences remain? Include web PHP, module releases, theme copies, proxy rules and integrations relevant to the failure.
• What is the smallest defined change, who owns any module compatibility patch, and how will the next update preserve it?
• Can the change be reversed after it writes data or calls an external service? Ask how orders and payments made during the incident will be reconciled.
• Which acceptance results will you receive for the affected markets, customer groups and staff workflow, and who will check production after reopening?

Agree one person to coordinate changes across the host, module supplier and shop developer. Keep a shared incident record so that one team does not restore an old package while another is testing the replacement. Close the handover with the verified cause, final change and remaining follow-up work.

Questions owners ask

What if the fault does not happen on staging?

Compare the request and relevant environment differences before deciding it has gone away. Live traffic, cache state, external credentials or a scheduled job can be part of the trigger. Arrange narrowly scoped production logging with your developer when copying the trigger safely is not possible.

What if the error happens only occasionally?

Keep an incident log with affected paths and business actions, then capture the matching server evidence when it recurs. Agree a targeted observation period or trigger with your developer. Repeatedly changing settings between occurrences makes an intermittent cause harder to distinguish.

Why does only one country or customer group see it?

Reproduce with the same language, currency, group, address, carrier and payment eligibility. Compare that context with a working one, changing a single relevant choice at a time. Country-specific taxes, restrictions or integration responses can lead customers through different code paths.

Does maintenance mode stop every change to shop data?

Do not assume it stops cron tasks, workers, API clients or payment callbacks. Identify the writers used by your shop and coordinate pausing, queuing or later reconciliation before a restore. Ask the payment maintainer how notifications behave during the window.

Can I send a browser Network export to support?

A HAR export can contain cookies, authorisation headers, tokens, submitted form data and customer details. Review and redact it before using a private support channel, preserving the request sequence and error needed for diagnosis. Share access credentials separately through the agreed secure method.

What should staff tell affected customers?

Record which journey is affected and the next action staff can safely take. Describe a payment as unresolved until it has been reconciled, and give the team one place to record customer references and follow-up. Promise a recovery time only when the person handling the incident has confirmed it.