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 Ægir 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. There are two ways to reach it; pick whichever is easier for you.

From the control panel (no shell needed). If the Ægir control panel and the site's admin still load, open the site and look at Reports → Recent log messages — the fatal error is usually near the top.

From your oN.ftp shell with Drush. Point Drush at the broken site with its alias — never a bare command in the site folder — using the right Drush for the site's Drupal version (see Running Drush for which is which and how to find your alias):

# Legacy Drupal 6/7 — system Drush 8, dotted alias:
drush @example.com watchdog-show --count=20

# Modern Drupal 8+ — the site's own Drush via vdrush, hyphenated alias
# (run from the platform app root, after 'Unlock Local Drush', as oN.ftp):
vdrush @example-com watchdog:show --count=20

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 the log reads empty, or Drush errors out before it can read it, the site is probably too broken to start up at all — in that case skip to Step 2 (the .dev. URL), which shows the error straight from the page.

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 (or ran vdrush without its @alias). 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:

TXT

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 changed your site's local.settings.php, that's a prime suspect. This is the one settings file you're meant to customise — Drupal loads it after BOA's own Aegir-managed 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.

Two important BOA facts before you touch it:

You can't edit settings.php itself. Aegir owns it and re-creates it on almost every control-panel task, so any change there is discarded.
local.settings.php is normally not writable from your shell — you have to unlock it first. In your limited shell you can't just open it or move it aside until you do.

To edit (or back out a change in) local.settings.php, follow BOA's supported procedure:

Create the control file sites/example.com/modules/local-allow.info.
Run the Reset password task on the site in the control panel — this makes sites/example.com/local.settings.php group-writable.
Now edit it (with rnano/rvim in the oN.ftp shell, or over SFTP) — remove or fix the offending line.
Test the site while logged in as admin.
Run the Verify task to restore standard permissions and remove the control file.

If you're not sure which line is at fault, load the .dev. URL (Step 2) first — it prints the exact error, pointing you straight at the culprit. There's more on how the two settings 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, use the right Drush for your Drupal version, always with the site's @alias:

# Legacy Drupal 6/7 — system Drush 8, dotted alias:
drush @example.com cc all

# Modern Drupal 8+ — the site's own Drush via vdrush, hyphenated alias
# (from the platform app root, after 'Unlock Local Drush', as oN.ftp):
vdrush @example-com cr

cc all is the Drupal 6/7 cache clear; cr ("cache rebuild") is the Drupal 8+ equivalent, and on a modern site only the site's own Drush (vdrush) can run it — the system Drush 8 can't. If the site was blank because of a bad cache, it'll spring back to life right after this. See Running Drush for what vdrush is, how to find your exact alias, and how to unlock the local Drush.

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 Ægir 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 D8+ site to apply the update. Run the site's Unlock Local Drush task first (or just apply the update from the control panel), then, as oN.ftp, from the platform app root (where vendor/ is), with the site's hyphenated alias:
SH
```
vdrush @your-site-example.com updb
```
On a legacy Drupal 6/7 site the system Drush 8 with its dotted alias works — drush @your-site.example.com updb. Reload the site afterwards. See Running Drush for what vdrush is, how to find your exact alias, and how to unlock it.
The site was white after an upgrade or migration. Run the Verify task on the site from the Ægir 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: show the error on screen

The safe, built-in way to make a site print its hidden PHP error on screen is the .dev. URL in Step 2 — that's exactly what it's for, it needs no file edits, and it never exposes errors to the public. Use it first.

If you genuinely need on-screen errors on the live URL for a short while, you can add them to the site's local.settings.php — but only through BOA's supported edit procedure (Step 3: create sites/example.com/modules/local-allow.info, run the Reset password task to make the file writable, edit, then Verify to restore it). The lines to add:

PHP

// 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';

Remove these lines the moment you're done, and re-run Verify. 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. And be careful: a typo in local.settings.php with no admin check first can itself cause a permanent white screen. The .dev. URL avoids all of this — prefer it.

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
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.