When something's wrong

Sooner or later a site does something you didn't expect — a page won't load, a change won't show up, a task in the control panel sits there and never finishes, or you've locked yourself out. This topic is your calm, first-stop guide for all of that. Almost everything here you can fix yourself, from the same two places you already work: the Aegir control panel in your browser, and your own oN.ftp shell.

The single most useful thing to know up front: most "broken site" moments aren't broken at all — they're stale. A cached page, a cache that needs clearing, a task still waiting its turn in the queue. So before you assume the worst, this topic walks you through the handful of quick, safe checks that clear up the large majority of problems in a minute or two. When something really does need the server — and a few things do — we'll say so plainly, and the fix is always the same: one short support request to your host. You never need root, and nothing here asks you for it.

What you can fix, and what you can't

It helps to draw the line early, because it saves you chasing a fix you can't reach.

Things that are yours to fix — all from the control panel or your shell:

A page that's blank, stale, or showing an old version — usually a cache.
A change to your code or content that isn't showing up yet.
A task that failed in the control panel — you can read why, and often just retry it.
A lost or forgotten admin password — you generate a fresh login link yourself.
A site that's out of step with its files on disk — the Verify task re-syncs it.
Running low on disk space — you can see what's using it and trim it.

Things that are your host's to fix — not because they're hard, but because they live on the server, which you don't manage:

The whole site (or every site) persistently returning a server error like 502 or 504, or the control panel itself being unreachable for everyone. (A block on just your address, or a brief 502 under load that clears on its own, is different and often yours to sort — see I'm blocked, or my site is slow.)
A service your sites depend on — the database, PHP, Nginx, Redis/Valkey, Solr — being down or misbehaving for everyone.
A task that's been stuck showing Processing for a long time and won't clear (the queue may be wedged on the server side).
Anything asking you to change a server setting, add RAM to a pool, or edit a file you can't reach.

For any of the second group, don't go hunting for a config file or a command — just open a support request and describe what you're seeing. Your host handles the server; that's the whole point of a hosted account.

The first things to try (they fix most problems)

Work down this short list before anything else. Each step is safe to run and safe to repeat, and one of them clears up most everyday trouble.

Give it a minute, then reload. BOA caches your pages and your code for speed, so a change you just made can take up to about 60 seconds to appear. Reload the page (a hard refresh in your browser) before deciding something's wrong.
Clear the site's cache. If a page is stale or a change won't show, clear the cache. The easy way is in the control panel: open the site's node and run Flush all caches. (You can also do it from your shell — see below.) Give it a few seconds and reload.
Run Verify. If the site seems out of step with itself — a setting isn't taking, files look wrong — run the Verify task on the site node. Verify re-checks and re-writes the site's configuration to match what's on disk, and it's completely safe to run any time. It's the single most useful "fix it" button in the control panel.
Check the task actually finished. A lot of "it didn't work" turns out to be "it hasn't happened yet." Look at the site's task list and confirm the last task shows Successful — not Queued, Processing, or Failed. What each of those means, and what to do about them, is the next section.

If those four don't sort it, the sections below go deeper by symptom.

Reading tasks in the control panel

Everything you ask BOA to do — Verify, a backup, a cache flush, a clone — runs as a task, and every task carries a status you can read on the site node. Learning to read these turns most mysteries into obvious next steps:

Queued — accepted and waiting its turn. Tasks run one at a time in order, so a fresh task may sit here for a short while, especially right after several others. This is normal; give it a little time.
Processing — running right now. Also normal — just wait for it to finish.
Successful — it worked. If your change still isn't visible after a Successful task, clear the cache and reload.
Failed — it ran but didn't complete. This is the one to look at: open the task to read its log (below), and you'll usually see a Retry button to run it again.
Warning — it finished but flagged something worth a glance. Open it and read the log to see what.

Two buttons are worth knowing:

Retry appears on a Failed task — click it to run the same task again once you've dealt with whatever the log pointed at.
Run Again appears on a task that finished fine — handy when you simply want to repeat it (for example, another cache flush).

When a task shows an error

Open the task and read its log — the control panel keeps a full log for each task, and the last few lines almost always name the real problem in plain terms (a file it couldn't find, a database it couldn't reach, a setting it didn't like). Fix what the log points at if it's yours to fix, then hit Retry.

If the log points at something on the server — a service that's down, a permission on a path you don't own — that's your host's to fix. Copy the relevant lines from the log into a support request; they're exactly what your host needs to help you fast.

A task stuck on "Processing"

If a task has shown Processing for a long time and clearly isn't moving, the task queue may be wedged on the server side — and unwedging it is a server-side job. Don't keep firing off new tasks (they'll just queue up behind the stuck one). Open a support request, name the site and the task, and ask your host to clear the stuck queue. It's a quick fix for them.

Fixing things from your shell

Your oN.ftp shell gives you a second set of tools for the moments the control panel doesn't cover. It's a restricted shell — it only reaches your own account, and it allows a curated set of commands (type ? or help after you log in to see the list). The ones that matter for troubleshooting:

Clear a site's cache with Drush. From inside a site's folder you can clear caches directly. On Drupal 8 and newer:
```
drush cr
```
On Drupal 6/7:
```
drush cc all
```
This does the same job as Flush all caches in the control panel — use whichever is closer to hand.
Look at what a site is doing. drush status and reporting commands, plus tools like grep, find, ls and du, let you inspect your own files and databases to understand a problem before you act on it.
See what's using your disk space. If you're near your quota (which itself causes odd failures — writes fail, caches can't be written), find the heavy folders:
```
du -sh ~/* ~/static/*
```
Common culprits are old backups under ~/static/files/dbackup/ and restored files under ~/static/restores/. Trimming those is covered in Backing up & restoring.

Your shell can't do everything Drush can — on purpose. A few Drush commands are blocked in your shell (running arbitrary PHP, self-updating Drush, creating databases, and similar), because they'd reach past your account or the site. That's a safety boundary, not a bug. If a task genuinely needs one of those, it's a control-panel task or a support request — not something to work around.

Common symptoms, quick fixes

A by-symptom index for the problems people hit most:

A page is blank or shows an old version. Almost always a cache. Wait a minute and reload; if it persists, run Flush all caches (or drush cr / drush cc all) and reload.
A code or config change isn't showing up. Same cure — clear the cache. If you deployed new code, also run Verify on the site so BOA re-reads the platform.
Every site persistently shows 502 / 504 / a server error. That's the server or a service, not your site's content. It's your host's to fix — open a support request. (A brief 502 that clears itself is BOA easing off under load — see I'm blocked, or my site is slow.)
You suddenly can't reach anything — but others can. Your address may have been temporarily blocked by BOA's abuse protection; it usually lifts on its own. See I'm blocked, or my site is slow.
The control panel itself won't load for everyone. Also server-side. Note the time and any error, and open a support request.
A task failed. Open it, read the log, fix what's yours to fix, and hit Retry (see Reading tasks above).
A task is stuck on Processing. Likely a wedged queue — a support request; don't pile up more tasks behind it.
You've lost the admin password. Generate a fresh one-time login link yourself — see the next section.
You're out of, or near, your disk quota. Find the big folders with du and trim old backups/restores; details under Backing up & restoring.
A site's settings won't take, or files look out of sync. Run Verify — it re-syncs the site to what's on disk.

Locked out: resetting an admin login

If you've lost or forgotten the admin password for one of your sites, you don't need your host and you don't need the database — BOA gives you a one-time login link from the control panel.

On the site's node, run the Reset password task. It generates a one-time login URL for that site's administrator. Open that link in your browser and you'll be logged straight in as the admin — then set a new password on your account page as usual. The link works once, so use it promptly and don't share it.

That's the safe, self-service way back in for any of your own sites. (Your login to the Aegir control panel itself, and your oN.ftp shell login, are separate — those are set up with your account, and if you've lost access to the control panel entirely, that's a support request to your host.)

In this topic

The pages here go deeper on the situations that need more than a quick check:

My site is broken (white screen) — the full playbook for a site that comes up blank: finding the real error in Drupal's log, undoing a change you just made, clearing caches, running Verify, and telling a "your site" problem apart from a "the server" one.
When an Aegir task fails — reading a failed task's log before you retry, the common causes you can clear yourself, what to do when a task is stuck on Processing, and when a wedged queue is a support request.
Password and access recovery — getting back into a Drupal login on your site (the one-time login link), your control panel login, and your oN.ftp shell/SFTP password.
I'm blocked, or my site is slow — when BOA's automatic abuse protection has temporarily blocked your address, and what a brief 502 or slowdown under load means (BOA eases off and heals itself).
Site health tasks — the one-click maintenance tasks in the control panel — Flush all caches and Rebuild registry — what each does and when to reach for it (plus where the old Run health check button went, and what to look at instead).

When to open a support request (and what to include)

You'll get help fastest when you hand your host the right details up front. For anything on the server side, include:

The site (its domain) and when it started.
What you see — the exact error text or status code (for example 502 Bad Gateway), or the task status.
The relevant task-log lines if a task failed — copy the last several lines from the task's log in the control panel.
What you already tried — cleared cache, ran Verify, retried the task.

That's usually everything needed for a quick turnaround. You don't need to diagnose the server yourself; you just need to describe what you saw clearly.

Good to know

Reach for cache and Verify first. The two safest, most effective buttons — Flush all caches and Verify — solve a surprising share of problems and can't hurt anything. Try them before assuming a site is truly broken.
Read the task log before you retry. A Failed task almost always explains itself in its last few log lines. Read, fix, then Retry — rather than retrying blindly.
Server errors and a wedged queue are your host's. A site-wide 502/504, a service outage, or a task stuck forever on Processing all live on the server. One support request, not a workaround hunt.
Everything you can fix, you can fix without root. The control panel and your oN.ftp shell are all you ever need for your own sites — and neither one asks you to touch the server.

Where to go next

Trouble getting into your shell or SFTP in the first place is its own page — see Connection problems.
Cache-clearing, Verify, and other Drush commands from your shell are covered in Drush in your instance.
Getting a site back from a backup — the Restore task and mybackup restore — is under Backing up & restoring.
Task names, control-file names, and command verbs are collected in the shared Reference.