My site is broken (white screen)

You loaded your site and got a blank white page — no content, no error, just white. This is Drupal's "something crashed and I've hidden the details from your visitors" screen, sometimes called a WSOD (White Screen of Death). It looks scary, but on a live site errors are meant to be hidden from the public, so the real message is simply somewhere you can't see yet.

The good news: you can find that message and fix most causes yourself, from the control panel and your own oN.ftp shell. No root, no server access. Work down this page roughly in order — the early checks are the quickest and catch the most common problems.

Almost everything here happens in your oN.ftp shell (the limited SSH login BOA gives you). If you're not sure how to connect, see Connecting to your account. And if the white screen appears right after you changed something, jump straight to Did you just change or deploy something? — that's usually the culprit.

First: is it just your site, or everything?

Before you dig in, check one thing. Try loading the Aegir control panel and one or two of your other sites.

Only the one site is white, everything else is fine — this is a site-level problem you can work through below. Keep reading.
Every site is down, or you get a 500 / 502 / 503 error page on all of them, and the control panel won't load either — that's not something in your site, it's the server itself. You can't fix that from your account, and there's nothing to edit. Skip to When it's the server, not your site.

Step 1 — Read the actual error in Drupal's log

Drupal writes the real error to its own log (the watchdog) even when the page comes up blank. This is your highest-value first check, so start here.

From your oN.ftp shell, point Drush at the broken site and ask for the most recent log entries:

drush @your-site.example.com watchdog-show --count=20

(Use your site's own alias in place of @your-site.example.com. Your aliases are set up for you by BOA — see Running Drush.)

Most of the time the fatal error is sitting right there near the top: a missing module, a PHP error in a custom module or theme, a database problem. That message usually tells you exactly what to fix — disable the offending module, revert the bad change, and so on.

If watchdog-show prints nothing useful, or Drush itself errors out before it can read the log, move on to the next steps.

If Drush gives you strange errors that look like server or Drupal problems, the usual cause is that you logged in as plain oN instead of oN.ftp. Reconnect as oN.ftp and try again — see Running Drush.

Step 2 — Load the site through its `.dev.` URL to see the error on screen

Every site can be viewed through a special development URL — an alias with .dev. in the name. When you open the site that way, BOA shows PHP errors right on the page instead of hiding them, and turns off the caching that can mask what's going on. It's the same site, same database, same files — just with the error message put back on screen for you.

So if you have a .dev. alias set up (for example www.dev.example.com), open it in your browser:

http://www.dev.example.com

Open it over http://, not https — BOA deliberately keeps .dev. names off the automatic certificate. If the white screen turns into a readable PHP error, you've found your answer.

Don't have a .dev. alias yet? You add it yourself on the site's edit form in the control panel, exactly like any other alias. The full walkthrough — how to name it, how to point DNS or your local hosts file at it — is on Developing your site, which is worth setting up once so it's ready the next time something breaks.

If `.dev.` works but the live URL is still white

This is a useful clue. When www.dev.example.com loads fine but example.com stays blank, the two differ mainly in caching — the live URL is served from cache, the .dev. one isn't. That points at a stale or poisoned cache rather than broken code. Clearing the cache (Step 4) usually sorts it out.

Step 3 — Undo a recent `local.settings.php` change

If you (or someone with access) recently edited your site's local.settings.php, that's a prime suspect. This is the one settings file BOA leaves for you to edit, and your site loads it last — after BOA's own settings.php — so a mistake in it (a stray typo, a wrong value, a leftover debug line) overrides everything and can take the whole site down.

Open it from your oN.ftp shell or over SFTP:

sites/example.com/local.settings.php

Look for anything you changed recently. If you're not sure, the quickest test is to temporarily move the file aside and reload the site. From inside the platform where the site lives:

mv sites/example.com/local.settings.php sites/example.com/local.settings.php.off

Reload the site. If it comes back, the problem is in that file — put it back and fix the offending line:

mv sites/example.com/local.settings.php.off sites/example.com/local.settings.php

Never edit settings.php itself to fix this — BOA regenerates that file every time the site is verified, so your change would vanish. local.settings.php is the right place for anything you want to keep. There's more on how these two files fit together on Developing your site.

Step 4 — Rebuild the cache

A stale or corrupted cache can produce a blank page all on its own, especially after an update or a config change. Clearing it is quick and safe, so it's always worth a try. From your oN.ftp shell:

# Drupal 8 and newer
drush @your-site.example.com cr

# Drupal 6 / 7
drush @your-site.example.com cc all

cr is "cache rebuild" for modern Drupal; older Drupal 6/7 sites use cc all instead. If the site was blank because of a bad cache, it'll spring back to life right after this.

For a modern Composer-managed Drupal 10+ site, its own bundled Drush sometimes does a more thorough job. If plain drush cr doesn't take, and you've unlocked the site's local Drush, use vdrush instead:

vdrush @your-site.example.com cr

See Running Drush for what vdrush is and how to unlock it.

Did you just change or deploy something?

If the white screen appeared right after a change, that change is almost certainly the cause — start by reversing it.

You just deployed new code or updated a module or theme. Roll back to the code that worked, or disable the module/theme you just added, then rebuild the cache (Step 4). A code deploy that half-applied — a missing file, an incompatibility with your Drupal or PHP version — is one of the most common WSOD triggers. See Developing your site for the safe way to deploy and back out.
You just ran, or half-ran, database updates. A half-finished update can leave the site in a broken in-between state until the rest of the updates run. The tidiest way to finish them is from the Aegir control panel (a Verify task, or Migrate onto an updated platform). To finish them from the shell instead, on a modern Composer-managed Drupal 10 or 11 site you must use the site's own bundled Drush — the legacy system Drush 8 can't start up a D10/11 site to apply the update. Run the site's Unlock Local Drush task first (or just apply the update from the control panel), then, from inside the site's directory:
```
vdrush @your-site.example.com updb
```
On a legacy Drupal 6/7 site the system drush @your-site.example.com updb works. Reload the site afterwards. See Running Drush for what vdrush is and how to unlock it.
The site was white after an upgrade or migration. Run the Verify task on the site from the Aegir control panel. Verify re-writes the site's settings.php and re-checks its setup, which clears up a lot of post-upgrade breakage. Then check local.settings.php (Step 3) for any leftover debug lines from before the upgrade.

If you can point at "it was fine until I did X", undoing X and rebuilding the cache fixes the great majority of these.

Step 5 — When you truly can't find it: turn on on-screen errors for this site only

If none of the above surfaces the error and you'd rather not rely on the .dev. URL, you can make this one site show its PHP errors on screen for a short while, by adding a few lines to its local.settings.php. Edit sites/example.com/local.settings.php and add:

// Show PHP errors on screen for THIS site — remove when done
error_reporting(E_ALL);
ini_set('display_errors', 'On');
ini_set('display_startup_errors', 'On');
$config['system.logging']['error_level'] = 'verbose';

Save, then reload the affected page (give it a minute for the change to take, or use the .dev. URL to see it instantly). The error that was hidden should now print.

Remove these lines the moment you're done. Leaving PHP errors visible to the public on a live site is a real security risk — it can leak file paths and internal details to anyone who visits. Delete the lines, save, and you're back to normal.

When it's the server, not your site

Sometimes the white screen — or a 500 / 502 / 503 error across all your sites, with the control panel down too — isn't anything in your account at all. The server itself is having a problem, and there's genuinely nothing for you to edit or run: you don't have access to the parts that are broken, and you shouldn't.

When that's the picture, the right move is to contact your host and describe exactly what you saw — which sites, the exact error or blank page, roughly when it started, and whether it's every site or just one. That short, specific report is the single most useful thing you can hand your host to get it fixed fast. Don't spend time trying to work around it from your account; there's nothing there to fix.

Running Drush — the drush/vdrush commands used throughout this page, and how to unlock a site's local Drush.
Developing your site — the .dev. development URL in full, plus how settings.php and local.settings.php fit together.
Connecting to your account — logging in as oN.ftp for the shell commands above.