When an Ægir 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 Ægir 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 Ægir 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 aliases — 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 aliases

That prints every site alias BOA has set up for your account. (On a modern Drupal 8+ site, list the hyphenated aliases vdrush uses with drush11 aliases instead — see Running Drush.) To check one site:

drush aliases | 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 Drupal (Drupal 8 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. It always needs the site's @alias (in the hyphenated form, from drush11 aliases) and must be run from the platform app root, as oN.ftp:

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 — the alias format, how to find your exact alias, and 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 Ægir 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.

Three Clone / Migrate failures you can clear yourself

Clone, Migrate, Backup, and Restore all share the same two bookends: pack the site's directory into an archive at the start, and unpack an archive near the end. A handful of log signatures from those steps come up again and again, and each has a self-service fix. Open the failed task's log and match the message.

"Could not back up sites directory for drupal"

The task stopped while packing your site's directory into a backup archive — before changing anything, so the live site is untouched.

Nearly always this means something inside the site's directory couldn't be read. The packing step has to read every file under sites/example.com/, and a single unreadable entry aborts the whole archive. The classic culprit is a .sass-cache directory left behind by Sass/Compass theme tooling, which creates its internal files with permissions nothing else can read.

Look for it from your oN.ftp shell — directories starting with a dot are hidden by most SFTP/FTPS clients unless you switch on "show hidden files", so the shell is the reliable way to see them:

cd ~/platforms/my-platform/sites/example.com
ls -la themes/mytheme/

If a .sass-cache (or a similar tool-generated cache directory) turns up, delete it or move it out of the site directory, then Retry the task:

rm -rf themes/mytheme/.sass-cache

A few things that look suspicious but are not the problem:

• A .git directory is fine. Version-controlled code inside the site directory is archived like anything else — only unreadable entries break the backup, and a normal .git is perfectly readable.
• Temporary files under files/tmp are fine. They're excluded from the archive automatically, so old advice about clearing them first no longer applies.

If nothing unreadable turns up and the task keeps failing on the same message, you're likely looking at ownership drift on the site's files — that's the server-side repair described in Permission and ownership errors above: a short support request, and your host runs the fix.

The mysterious sites/example.com.restore directory

During a Clone, Migrate, or Restore, the incoming copy of your site is unpacked next to the live one, into sites/example.com.restore. When the copy is ready, the two directories are swapped in one quick move — the new copy becomes sites/example.com, and .restore is left holding the old site. That's your safety net: if the task fails after the swap, it swaps them straight back, and when the task succeeds, the .restore directory is removed automatically.

So spotting a .restore directory while a task is running is normal — leave it alone. What's not normal is one still sitting there when no task is running: it means an earlier task died hard, before its cleanup. And a stale .restore blocks the next attempt — the fresh task has nowhere to unpack, and its log fails early with a line like "Failed to extract the contents of …" naming the .restore path.

The fix, from your oN.ftp shell:

1. Check the live site first. Load sites/example.com's actual website in a browser and make sure it's the version you expect — the rollback swap either completed or was never needed.

2. Move the leftover out of the way, and retry the task:

   SHCopy

   cd ~/platforms/my-platform/sites
   mv example.com.restore example.com.restore-old
   

   Once everything's confirmed healthy you can rm -rf the renamed copy — or keep it a few days as a spare copy of the old site; it costs nothing but disk space.

If the move is refused with a permission error, the leftover is owned in a way your shell user can't touch — that's the same one-line support request as any other ownership repair.

A Migrate or Clone that keeps failing after re-using a site name

If a task fails on a site whose domain name existed on your account before — a re-created site, a clone brought back under an old name, a domain moved between sites — the culprit is often the object cache. Your sites' cached entries live in a shared in-memory store (Valkey/Redis), keyed by the site's domain name, and they outlive the site's database: deleting and re-creating a site doesn't clear them. The new site then reads the old site's leftovers mid-task and fails in confusing ways.

The self-service fix is to take the object cache out of the picture for one run:

1. Edit the site's INI file, sites/example.com/modules/boa_site_control.ini, and set:

   INICopy

   redis_cache_disable = TRUE
   

2. Wait a minute for the setting to take effect (see Which file do I edit?), then Retry the failed task.

3. Once the task succeeds, set it back to FALSE (or comment the line out again) — you want the cache back for day-to-day speed.

How the shared store and its per-site key prefixes work — and why a re-used name inherits stale entries — is covered on The Redis/Valkey object cache.

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:

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

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 aliases, 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.
• The Redis/Valkey object cache — the shared store and per-site key prefixes behind the re-used-name Migrate failure above.
• 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 — the consolidated indexes of configuration variables, control-file settings, and BOA's commands and helper tools.