502 after a deploy

A deploy builds a release from your commit and activates it on live. When the site answers with a server error right after, the new release is the first suspect. The old release is still on the server, so the fastest move is to roll back and then find the cause with the site running.

What you see

• A blank page or "502 Bad Gateway" within seconds of the deploy finishing.
• wp-admin shows a PHP fatal error that names a file in a plugin, a theme, or vendor/.
• The deploy job shows as done, but the homepage no longer answers.
• The build failed instead. In that case Avaloi created no release and live did not change, so the error has another cause. Start at step 4.

Check these first

1. Roll back if visitors are waiting. Open the site, then Code. Choose the previous release and click Rollback, or call POST /v1/releases/{id}/activate. The older code goes live in under 10 seconds, with no new build. Rollback changes code only: your database and uploads stay as they are. Avaloi keeps the last 10 releases.
2. Read the build log. On the Code tab, open the newest build, or call GET /v1/environments/{id}/builds and GET /v1/builds/{id}/log. A build step that printed a warning but did not fail can still leave a release that lacks vendor/ or compiled assets. A step that failed means no release and no change to live.
3. Check the PHP version. The php key in avaloi.yml sets the version for the build and for the running site. A plugin or theme that does not support the new version fails on the first request. If you changed the version under Tools, PHP settings, around the same time, Avaloi checked the homepage and rolled the version back on its own when it answered with a server error. The page shows why.
4. Read error.log. Open Logs, pick error.log, and filter by Error. A PHP fatal error names the file and line. Two causes show up most: a missing class because composer install did not run in the build, and a plugin that writes into its own folder on a read-only release. For the second, the Code tab suggests the folder to make writable.
5. Check the build steps and deploy hooks in avaloi.yml. Build commands run in order in a fresh container, and whatever they create is part of the release, so a missing composer install or npm run build step leaves files out. Deploy hooks run after the release is mounted, have about one minute in total, and use the WP-CLI allowlist, so a command such as wp eval is refused.
6. Open the deploy job. The Jobs button in the top bar lists recent jobs. A failed job says what went wrong in plain words, and GET /v1/jobs/{id} returns the same.

Fix it

• If a build step is missing, add it under build in avaloi.yml, commit, and push to main. Watch the build in the Code tab, then click Deploy.
• If a plugin needs to write into its folder, add the folder under writable in avaloi.yml, push, and deploy. PHP files in writable folders do not run.
• If the PHP version is the cause, set php in avaloi.yml to a version your code supports, in quotes, and deploy again. Or keep the version and update the plugin in your repository.
• If a deploy hook failed, fix or remove it. Avaloi clears the server cache after the hooks on its own, so you do not need a hook for that.
• If the error survives a rollback, the release is not the cause. Restart PHP from Tools and read php-fpm.log, then check the PHP settings.
• Try the fix on staging first. Push to the staging branch, deploy on staging, and open it. When it works, merge into main from the Code tab and deploy on live.

A snapshot is taken before every deploy and kept 48 hours. If the deploy also changed the database through a hook, open Backups and restore the database from that snapshot. Restoring asks you to type the target's name.

Still stuck

Write to [email protected] with the site name, the environment, the request ID from the API response or the job ID, and what you tried. Add the commit you deployed and the first error line from error.log.

Related

• How Git deploys work
• avaloi.yml reference
• View logs
• Change PHP settings
• Jobs and progress
• Staging and branch environments
• Backups