Troubleshoot

Fix a Space that does not create (disk, container engine, virtualization, the two-VM limit, Local Network), find help for agents and computers that will not connect, and ask for help.

Most problems are a Space that won't create, or an agent or computer that won't connect. This page covers a failed create in detail and points to the fix for the rest.

A Space won't create#

When a Space can't be created, Cua Spaces shows Couldn't create this Space with the reason, a Try again button and a Remove from list button.

Try these first#

Press Try again. A retry reuses the image that already downloaded, so it is usually much faster than the first attempt.
Update Cua Spaces to the latest version. See Updates in Install.
Run the checks in a terminal:

cua runtime doctor     # which container engines and VM runtimes this computer has
cua doctor             # host checks in one report

Find your reason#

Match the reason the app shows to the rows below. The word in parentheses is the fixed name Cua uses for the cause. See Create failure kinds for the full list.

What it means	What to do
The image download failed, was refused or stopped partway (`image_pull_network`, `image_pull_not_found`, `image_pull_auth`, `image_pull_rate_limited`, `image_pull`)	Check your network and try again. Finished image layers are kept, so the next attempt resumes. If the registry rate-limited you, wait a few minutes. If you use your own image, check its name and that you can pull it.
Not enough disk space (`insufficient_disk`)	The New Space screen shows how much space is needed and available. A macOS Space needs about 50 GB. Free some space, or delete Spaces you no longer need with `cua spaces delete`.
No container engine is running (`runtime_missing`, `runtime_not_running`, `runtime_permission`)	Start Docker Desktop, or install a container engine such as Docker, Colima or Podman. If the message says permission denied, give your user access to the engine. Run `cua runtime doctor` to check.
This computer can't run virtual machines (`virtualization_unavailable`)	macOS Spaces need an Apple silicon Mac. On Linux and Windows, turn on hardware virtualization in the firmware settings. Or create a Linux container Space instead.
Two macOS VMs already run (`vm_limit`)	Apple allows two macOS VMs at a time on one Mac. Stop or delete one, then try again.
The VM started but never answered (`vm_boot_timeout`, `services_unreachable`)	The first macOS Space unpacks a large image and can run out of time. Try again: the image is already downloaded, so it is much faster.
macOS blocked the connection to the new VM (`local_network`)	Open System Settings, Privacy & Security, Local Network, turn on Cua Spaces, then try again.
"The Cua daemon isn't running. Start Cua, or run `cua daemon start`."	Open Cua Spaces, or run `cua daemon start`.

Creating on another computer#

To create a Space on one of your other computers, that computer must be online, provide Spaces, and be set up for your account. If the create fails with a name such as ambiguous_host or host_capability_missing, see the spare Mac errors.

Stop a create that is stuck#

Press Cancel in the toolbar of a Space that is being created. Cua Spaces removes the partial Space and keeps the finished image layers, so the next attempt resumes. See Cancel a create.

Ask for help#

Versions of Cua Spaces after 0.9.4 add Send a report... to a failed Space. It builds a report from the error, the phase it failed in, the image and the app and system versions. Before anything leaves your computer:

You review the report and can edit it or leave parts out.
Cua removes tokens, email addresses, home folders, hostnames and public IP addresses.
Open email starts a message to Cua support (support@trycua.com) in your mail app. Nothing is sent until you press Send there.

On any version, you can email support@trycua.com with the reason shown, your system, and the Cua Spaces version from Settings, About.

Reports are private: they go to Cua support by email, never to a public issue. Remove anything you don't want to share before you send.

What you see	Where to look
The agent has no `cua` tools, or can't reach a Space	If it doesn't work in Connect your agent
A computer never appears, or shows Offline	If it doesn't work in Add a computer
An error name such as `capability_missing` or `permission_denied`	Errors in the Spaces reference
You want Cua Spaces gone, or a clean reinstall	Uninstall Cua Spaces, then Install
Something else	Email support@trycua.com as described above

Next#

Create a Space: images, progress, GPUs.
Install: requirements for each system.