Install and startup problems

The install stops part way through

Usually out of disk. The published images need about 20 GB; keep 40 GB free, plus 25 GB more to build from source.

df -h /var/lib/docker

The seed and the recovery actor

On a Quasar-owned machine the seed checks every 30 seconds and logs only changes. Every warning or error carries a token=.

docker logs quasar-seed
docker logs quasar-recovery
docker exec quasar-seed quasar-recovery status       # the seed's last check
docker exec quasar-recovery quasar-recovery status   # services, blockers, last update

What the seed says

Log	Meaning and fix
seed-actor-created	It created and started quasar-recovery. The install continues there.
a recovery actor exists; nothing to do	Normal after the first install.
seed-inputs-invalid	An input is missing or invalid (the line names it). Nothing was created. Fix the stack or docker run line and start the seed again.
seed-agent-image-unavailable	An image can’t be pulled (the line names it). Nothing was created; retried at the next check.
seed-self-invalid	A mount is missing, the volume isn’t quasar-machine, or the seed image has no digest. Start it by digest with both mounts.
seed-uninstalled	The machine was uninstalled. The seed stays idle.
seed-file-unknown-format, seed-file-unreadable	The seed’s state file is unknown or invalid. The seed stays idle.
seed-name-taken	A quasar-recovery container without this installation’s labels exists. Remove it and the seed creates its own.
seed-actor-unstarted	A recovery actor was created but never started. Run docker start quasar-recovery.
seed-actor-started	quasar-recovery had been stopped by hand, so the seed restarted it. To keep it stopped, stop the seed first.
seed-actor-stopped	No recovery actor is running and the seed won’t start it (interrupted update, or two actors). Nothing can be updated meanwhile. Run the command the line names.
seed-engine-unreachable, seed-pull-failed, seed-create-failed, seed-start-failed, seed-look-failed	Retried at the next check.
seed-engine-config	The engine endpoint (for instance DOCKER_HOST) is unusable. The seed exits. Fix the socket mount or variable.

What the recovery actor says

Log	Meaning and fix
actor-resume-failed	The install failed (engine unreachable, owner conflict). Retried at the next start.
actor-role-invalid	QUASAR_ROLE names a role this build doesn’t install. The actor exits.
actor-engine-config	The engine endpoint is unusable. The actor exits.
actor-no-gpu, actor-gpu-probe-unreadable	No usable GPU found. The agent is installed anyway; readiness reports the gap.
actor-gpus-served	The agent gets the NVIDIA device setup. Normal.
actor-gpu-injection-unavailable	An NVIDIA GPU was found but this engine can’t pass it through. Follow NVIDIA setup for your engine, restart it, then remove the agent container.
actor-gpus-refused	The engine refused the GPU. Fix the NVIDIA Container Toolkit (or the CDI spec on Podman and rootless Docker), then remove the agent container.
actor-gpus-probe-retry	The engine didn’t answer the GPU probe. Asked up to three times.
actor-helper-name-taken	A foreign container holds quasar-gpu-probe or quasar-secrets-writer. Remove it.
actor-lease-unavailable	A second recovery actor on the same machine. Only one runs.
actor-input-ignored	A later start had different inputs. Machine state wins after the first install.
actor-installation-label-differs	A hand-started actor was later given a seed. Run docker rm -f quasar-recovery; the seed re-creates it.
actor-trust-config-invalid	Invalid signature mode or trusted key. The start stops.
actor-spec-differs	The running agent differs from what the actor would create. Left as is.
actor-socket-bind-failed	The quasar-recovery-agent volume isn’t mounted at /run/quasar-recovery.
actor-socket-busy	Too many connections; one was closed.
actor-socket-failed	The agent socket stopped. The actor exits and restarts.
actor-console-refused, actor-submit-refused	A console-mode or update request was refused; the line names why.
actor-attempt-failed, actor-verification-failed	An update didn’t complete. An unhealthy new agent is rolled back. The apply history has the reason.
actor-journal-unreadable	The update record is corrupt or from a newer actor. Updates wait until it’s dealt with.
actor-journal-write-failed	The update record couldn’t be written. Check free space on the quasar-machine volume.
actor-kept-not-removed	The old container couldn’t be removed. The next update removes it.

The full list is in the repository’s docs/configuration.md (“Seed”, “Recovery actor”).

A refused or failed update shows one of these reasons on the Releases tab:

Reason	Fix
owner_conflict	A Quasar-like container not created by this install (such as an old Compose stack) is in the way. Nothing was replaced. Remove it and whatever re-creates it.
recipe_unsupported	This recovery actor can’t install the new image. Update the recovery actor first.
backup_failed	The database dump failed or had no room. Nothing changed. Free space on the quasar-machine volume and apply again.
backup_unconfirmed	The update migrates your own database. Take a backup, tick the confirmation, apply again.
interrupted	The actor restarted before changing anything. Apply again.

A failed install: fix the inputs, then start the seed again. If the recovery actor already exists, run docker restart quasar-recovery instead. It retries using the machine’s saved state; changing the seed’s inputs does not reconfigure an installed machine. See changing an input.

The control plane will not start

docker logs quasar-control-plane

(Legacy Compose: docker compose -f deploy/docker-compose.yml logs quasar-control-plane.)

Symptom	Fix
no migration found for version N	You rolled back below the database’s version. Redeploy the version that has the migration. See Upgrading.
Cannot connect to the database	Postgres isn’t up yet, or it isn’t reachable. On legacy Compose, POSTGRES_PASSWORD in your shell overrides deploy/.env; unset it. On an owned install, quasar-recovery status names the database address to check.
Malformed allowed origins	Each QUASAR_ALLOWED_ORIGINS entry must be exact scheme://host[:port], no path.

A container reports “no command specified”

A Compose overlay cleared the command. Check which overlays you stack, and in what order.

The node agent starts but never registers

On the agent’s host:

curl http://127.0.0.1:9091/health

"connected": false means it can’t reach the control plane. Check:

• CONTROL_PLANE_URL is right and reachable from that machine, including port 8080.
• You used the QUASAR_ENROLLMENT string from Fleet ▸ Hosts ▸ Add host, or ENROLLMENT_TOKEN set to a token minted there (the part of the string after its last .).
• The address is wss://. ws:// to anything but localhost is refused unless QUASAR_ALLOW_PLAINTEXT_AGENT=1.

An agent that enrolled before and now can’t has lost its node secret. Enroll it again with a fresh string.

The GPU is not detected

ls -l /dev/dri

No renderD128: the host driver isn’t loaded. If the nodes exist but the agent can’t open them, check group and mode, and that the device is passed to the container. For NVIDIA, check nvidia-smi on the host, then follow the engine-specific checks in NVIDIA setup.

The GPU is detected but there is no encoder

no VA H264 encoder found while vainfo works:

• A stale GStreamer plugin cache. Recreate the container.
• MESA_LOADER_DRIVER_OVERRIDE or LIBGL_ALWAYS_SOFTWARE is set. They must be unset, not empty. Don’t copy both the software and hardware blocks from .env.example.

NVIDIA graphics libraries are missing

Use the full graphics driver, not a CUDA-only installation. Follow NVIDIA setup for prerequisites, container access and driver compatibility. Quasar can provision missing graphics libraries in a driver volume; the host’s readiness card shows progress and gaps. It cannot repair the kernel module. After a host driver update, recreate the agent container.

Input devices are not working

ls -l /dev/uinput

It normally appears on demand. If it’s missing, the kernel lacks the uinput module: sudo modprobe uinput shows why.

If it exists, the agent must be able to open it for writing. The uinput and input_probe readiness checks test this. On a rootless engine, install the device rules and restart the agent. See Readiness checks.

The agent does not start after a reboot (Podman)

cannot stat /run/quasar-agent: No such file or directory: a reboot emptied /run.

Mode	What to do
Rootful	Nothing. The recovery actor makes the directory and starts the agent when it starts. If it did not, check sudo podman logs quasar-recovery for actor-runtime-dir-failed, and that podman-restart.service is enabled.
Rootless	Step 4 of Install rootless, then podman start quasar-node-agent as quasar.

The console is unreachable from the network (rootful Podman)

The control plane answers on 127.0.0.1:8443 on the host, but connections from another machine hang. Check sudo iptables -S FORWARD. If it says -P FORWARD DROP, Docker also runs on this host and is dropping Podman’s forwarded traffic. Fix it as Docker on the same machine says. If the policy is ACCEPT, check that your firewall opens the port.

A GPU-less host will not start

Legacy Compose: comment out the /dev/dri device line in deploy/docker-compose.yml. Owned installs only declare devices that exist.

The web app is blank after a redeploy

Hard refresh. If that doesn’t help:

docker restart quasar-control-plane

The Releases tab says a target cannot be updated from here

The page prints the recipe under the Targets table.

Reason	Fix
Built from source	Update it the way it was installed: deploy/redeploy.sh <va|nvidia> <ref>.
No recovery actor answers	Check docker ps -a --filter name=quasar-recovery and docker logs --tail 50 quasar-recovery. The seed re-creates a missing actor; restart the seed if it’s gone too. Legacy Compose has no actor: update by hand or move the install.
Must update before it can be managed	Apply the update offered.
A preflight check failed	Follow the fix shown. For other owner’s container in the way, remove that container and whatever re-creates it.
Target has not reported what it is running	An old agent. Upgrade it once by hand. See Updating Quasar.

An apply failed with namespace_rejected

The image is outside QUASAR_UPDATER_ALLOWED_NAMESPACES (default: the project’s own namespace), usually after pointing at a fork’s registry. On legacy Compose, set it in the host’s deploy/.env. On an owned machine:

docker exec -it quasar-recovery quasar-recovery reconfigure --yes \
  QUASAR_UPDATER_ALLOWED_NAMESPACES=ghcr.io/accreleus/quasar,<your namespace>

On the first machine this also replaces the control plane.

The control plane is unhealthy after an update

fatal: tls: write TLS key /var/lib/quasar-control/tls/key.pem: permission denied

The stack once ran a source build, so quasar-control-tls is owned by root. See the one-time fix. Don’t mix: update published images from the console, source builds with redeploy.sh.

An unrecognised migration version means an older image on a newer database. See the hard rule.

“Quasar was updated. This page is running the previous build”

Press Reload in the toast, or refresh. Nothing is wrong.

Still stuck

Collect logs with the commands on Health and logs and attach them to a report with secrets removed. From a repository checkout that runs Quasar, make diagnose does this in one pass.