Website recovery
Recover a website that failed after a PHP update
Find the cause of a 502, blank page or fatal error after a PHP update. Protect orders and recent data before changing packages, settings or application code.
In this article
Protect orders before another change
A website owner, host and developer may each control a different part of recovery. Name one person to coordinate them. Record when the failure began, which PHP or application release changed, and which customer tasks are affected.
If orders are failing, agree which writes to pause, including background jobs and incoming payment events. Do not repeat a customer payment to reproduce an error. Check its state with the payment provider first.
Keep administrator access that works without the broken website. Before restoring a backup, preserve current files and database records and decide how newer orders, payments, stock changes and uploads will survive. Test recovery on an isolated copy. WordPress explains complete backups.
Match one failed request to its logs
An HTTP 502 means a gateway received an invalid response from another server. It does not identify PHP as the cause. A content delivery service, reverse proxy or web server can return it. Record the actual status of a blank page, too. HTTP defines 502 here.
| Evidence | Next check | Usual owner |
|---|---|---|
| 502 and a backend connection error | PHP service, destination socket or address, permissions and startup log | Host or administrator |
| 500 or blank response with a fatal PHP error | First matching error, file, line and component version | Developer |
| An extension fails to load | Extension build, intended PHP version and configuration | Administrator |
| Only one task fails | That route's code, dependencies and backend | Developer with host logs |
Use hostname, path, timestamp, timezone and request ID to match proxy, web-server, PHP and application records. A nearby error from another request can send recovery in the wrong direction.
For a 502, trace the connection to PHP
PHP-FPM runs groups of PHP worker processes, called pools. Each pool listens on a socket or network address. The website's web-server configuration must point to that destination.
Compare Nginx's fastcgi_pass, or Apache's FastCGI handler, with the intended pool's listen value. Then inspect the service that owns that pool. See Nginx, Apache and PHP's pool settings.
Check the failure before restarting services. A restart can interrupt other sites and cannot repair a wrong socket path. Keep socket access limited to the users that need it.
For a fatal error, identify the component
A TypeError, incompatible declaration or removed function can point to application compatibility. An undefined function may instead come from a missing extension, dependency or disabled function. Identify what should supply it before installing packages or lifting restrictions.
Check supported PHP versions for the failing component and migration notes for each branch crossed. Reproduce the task on a protected test copy. See PHP 8.0 incompatibilities and the PHP 8.5 migration guide.
Use private logs rather than public error output. PHP warns that displayed errors can disclose sensitive information. PHP error settings.
Check the website's settings
These commands inspect PHP selected by the terminal:
php -v
php --ini
php -mThe website may use another executable, configuration and extension set. Ask the operator for its loaded files and pool overrides. Compare them with the last working setup. PHP configuration lookup.
Use your host's supported controls. Hand-editing generated configuration can affect other domains or be overwritten. Avoid a public phpinfo() page, which can reveal configuration and request data.
Test a repair that matches the cause
| Established cause | Possible repair | Check afterward |
|---|---|---|
| Wrong pool or failed service | Repair handler mapping or startup failure | An uncached request reaches intended PHP |
| Missing extension or changed setting | Restore the supported component or setting | No startup error; affected feature passes |
| Application incompatibility | Deploy a tested component or code fix | Original failure and related tasks pass |
| No tested repair available | Keep affected functions paused or restore a verified compatible release | Recent data preserved; restored PHP has security coverage |
nginx -t and apachectl configtest check configuration syntax. They do not test a PHP connection or checkout. A PHP rollback also cannot reverse database changes made by an application update.
After an approved production change, check uncached read-only pages, fresh logs, scheduled tasks and integrations. Use a separate agreed test plan for actions that send messages or move money. Record any live payment behavior left untested.
Give support a useful failure report
Send the domain, account reference, failure time and timezone, failing path and status, old and new versions, a short redacted error excerpt, affected domains, backup time and actions already tried. Explain whether orders remain open.
Ask the host to identify the domain's PHP service, full build, settings and extensions. Ask the developer to demonstrate the repair on staging. Agree who approves production changes and handles recovery. Remove passwords, tokens, cookies and customer details from shared logs.
Questions about update failures
Why does the home page work while checkout fails?
The home page may be cached or use different code. Compare a working dynamic request with the failed task. Account for the first transaction before submitting another payment.
Should I choose the previous PHP version?
Record the current setting. Confirm that the previous build has security coverage and fits the current application and database before an approved switch.
Why does PHP work over SSH?
The terminal may select another installation. Trace the website's handler and inspect that runtime separately.
What if my host will not provide raw logs?
Ask support to locate the matching error and confirm the domain's PHP service, settings and extensions. Keep unanswered checks open.
Can a front proxy return the 502?
Yes. Identify which layer returned it and inspect its upstream error before changing PHP.
Should I open socket permissions to everyone?
No. Restore the intended owner, group or access rule. Broad access can defeat separation between sites.
Is a passing PHP lint check enough?
Lint checks syntax without running the application. Repeat the failed task and nearby behavior on the intended PHP.
Sources
Before recovery returns a site to older PHP, check its maintenance and upgrade options.