When an Aegir task fails

Everything you ask the control panel to do — Verify a site, take a backup, clone, migrate, flush caches — runs as a task. Most of the time a task just works and you never think about it. But now and then one comes back Failed, or sits on Processing and won't move on. This page is what to do when that happens.

The good news is that a failed task is usually one of a small handful of everyday situations, and almost all of them you can clear yourself — from the control panel and your own oN.ftp shell, no root and no server access. Work down this page roughly in order: the early steps are the quickest and fix the most cases. When a task really does need the server, we'll say so plainly, and the fix is always the same short support request to your host.

If a whole site is white or won't render at all — rather than a task failing — start with My site is broken instead; come back here if the trouble turns out to be a stuck or failing task.

First: read the task, don't just retry it

When a task comes back Failed, the single most useful thing you can do is open it and read its log. The control panel keeps a full log for every 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 module it didn't like, a permission on a path.

To read a task log:

  1. Open the site node (or platform) the task ran on.
  2. Find the task in its Tasks list — the failed one is flagged.
  3. Open it and read the log. Scroll to the bottom: the real error is almost always in the last several lines, not the top.

Resist the urge to hit Retry straight away. A blind retry on the same broken state usually fails the same way — or, worse, leaves things in a slightly worse state than before. Read first, fix what the log points at, then retry.

If the log points at something on the server — a service that's down, a path you don't own — copy those last lines into a support request. They are exactly what your host needs to help you quickly.

Re-run Verify — the safe first fix

For a great many "a task failed" or "the site's acting strange" moments, the fix is simply to run Verify again.

On the site node, run the Verify Site task. Verify re-checks the site and re-writes its configuration to match what's actually on disk — its Nginx vhost, its settings.php, its aliases, its database connection. It's completely safe to run any time, on any of your sites, and it's the closest thing BOA has to a "fix it" button. If a site drifted out of step with itself — a setting didn't take, files look out of sync, an alias went missing — Verify is what pulls it back into line.

A couple of things worth knowing:

  • Verify after you deploy code or change a platform. If you pushed new code or swapped something on the platform, run Verify on the affected site(s) so BOA re-reads the platform and updates the site to match.
  • Don't Verify everything blindly when something's already wedged. If a site is in a genuinely broken state, a Verify that hits an error mid-run can leave it no better off. Read the failing task's log first, fix the actual cause, and then Verify. Verify is safe — but it's most useful aimed at a known problem, not fired at everything at once.

The Lock / Unlock Local Drush cycle — the "platform is in a weird state" fix

Sometimes it isn't one site but the whole platform that's out of step: site tasks (Verify, Clone, Migrate) on that platform start failing for no obvious reason, or you see a Drush-version or "declaration" error in a task log. The reliable cure is a short cycle of platform tasks that resets the platform to the clean state Aegir expects.

On the platform node, run these three tasks, in this order:

  1. Verify + Lock Drush
  2. Unlock Local Drush
  3. Verify + Lock Drush (yes — run it again)

That's the full recovery cycle. The middle Unlock Local Drush step clears the platform's locked-down state; the final Verify + Lock Drush re-establishes the canonical, locked state Aegir wants. Running it fixes most cases where:

  • A platform is "in a weird state" after a task failed partway through.
  • Site tasks on that platform fail with Drush-version or code-path errors.
  • A site's local Drush lock is out of sync with its files.

It's safe to run this cycle whenever a platform's site tasks are misbehaving and a single Verify didn't sort it. If the cycle itself won't complete — a task in it keeps failing — read that task's log, and if it points at the server, open a support request.

vdrush and drush sa — checking a site from your shell

After a failed Clone or Migrate, a site can end up half-there: the control panel shows a node, but the site's Drush alias on disk is missing or stale, so your shell can't find it. A couple of quick checks from your oN.ftp shell tell you what state things are really in.

These commands run in your oN.ftp shell — the limited SSH login, not the plain oN login. If Drush behaves oddly, the usual cause is that you connected as oN instead of oN.ftp. Reconnect and try again. See Connecting to your account.

List your site aliases to see whether the site BOA thinks exists actually has a working alias on disk:

drush sa

That prints every site alias BOA has set up for your account. To check one site:

drush sa | grep your-site.example.com

An empty result means there's no alias on disk for that site — which is exactly what a failed Clone or Migrate leaves behind. The fix is to run Verify Site on that site in the control panel: Verify regenerates the alias from the site's record, and your shell can find it again.

vdrush is BOA's shortcut for a site's own bundled Drush — the copy that modern Composer-managed Drupal (Drupal 10 and up) ships inside the site under vendor/. If a task on a modern site failed and you want to poke at it directly, vdrush is how you reach the right Drush for that site:

vdrush @your-site.example.com status

vdrush only works once the platform's local Drush is unlocked — run the Unlock Local Drush platform task first, and Lock Local Drush again when you're done. The full walk-through, including which PHP version Drush runs under, is on Running Drush — this page just points you at it, since a failed task on a modern site is the most common reason you'll need it.

Permission and ownership errors in a task log

A fairly common failed-Verify log line is a permission complaint — something like "could not write to…" or a file-ownership error. It usually means a Composer run or a manual file operation left some files owned or permissioned in a way Aegir didn't expect.

Fixing file ownership on the platform is a repair that has to run with root privileges — so on a hosted account it isn't something you run from your own shell. This is a genuinely two-minute job for your host: open a support request, name the site or platform, and paste the permission/ownership line from the task log. They run BOA's permission-repair helper for you, and then you re-run Verify Site. There's no root command for you to find here and nothing for you to work around — the log line plus the site name is all your host needs.

When a task is stuck on "Processing"

A task that's been showing Processing for a long time and clearly isn't moving is a different animal from a Failed one. Tasks run one at a time, in order, so a fresh task legitimately waits its turn — but a task that's genuinely wedged, not just waiting, points at the task queue being stuck on the server side. That's a server-side fix.

So if a task is stuck:

  • Don't pile on more tasks. New tasks just queue up behind the stuck one and make it harder to see what's happening.
  • Open a support request, name the site and the stuck task, and ask your host to clear the queue. It's a quick fix for them.

You can tell the two apart by watching: a task that's really processing eventually finishes or fails; one that's wedged sits unchanged for a long time while nothing else moves through the queue either.

What's yours to fix, and what's your host's

A quick line to save you chasing a fix you can't reach:

Situation What to do
Task Failed with a clear cause in the log Fix the cause, then Retry the task
Site "acting strange", setting won't take Run Verify Site
Platform's site tasks all failing The Verify + Lock Drush → Unlock Local Drush → Verify + Lock Drush cycle
Site alias missing after Clone/Migrate Check with drush sa, then Verify Site to regenerate it
Modern (Drupal 10+) site to inspect by hand vdrush after Unlock Local Drush — see Running Drush
Permission / ownership error in the log Support request — your host runs the permission repair
Task stuck on Processing, queue wedged Support request — your host clears the queue
Log points at a down service, or a path you don't own Support request, with the relevant log lines

Anything in the "support request" rows lives on the server, which you don't manage — that's the whole point of a hosted account. You never need root to recover a task, and nothing on this page asks you for it.

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

You'll get the fastest turnaround when you hand your host the right details up front:

  • The site (its domain) and which task failed or is stuck.
  • The last several lines of the task log — copy them straight from the control panel; that's where the real error is.
  • What you already tried — re-ran Verify, ran the Lock/Unlock cycle, checked drush sa.

You don't have to diagnose the server yourself. Describe what you saw clearly and let your host take it from there.

Related

  • My site is broken — a site that's white or won't render at all, rather than a task failing.
  • Running Drush — vdrush, drush sa, and choosing the PHP version Drush runs under, all from your oN.ftp shell.
  • Cloning & migrating — the Clone and Migrate tasks that most often leave a site half-there.
  • Connecting to your account — logging in as oN.ftp for the shell commands above.
  • Backing up & restoring — getting a site back from a backup when a task can't be recovered.
  • Reference — task names, control-file names, and command verbs in one place.