Troubleshooting

Problems that stop metralectl run before a model ever loads, and what to do about each. If your problem is a model that starts and then misbehaves, the Quickstart has a section for that.

permission denied talking to Docker

permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock

What it means. Docker is installed and running. The daemon answered your request and refused it, because your user is not in the docker group. This is the single most common reason a fresh DGX Spark cannot launch a model, and it has nothing to do with the hardware.

The fix, once:

sudo usermod -aG docker $USER
newgrp docker          # or log out and back in

usermod changes your groups; it does not change the groups of a shell that is already running. newgrp docker starts a shell that has the new membership, and logging out and back in achieves the same thing for every shell.

Confirm it took:

docker info --format '{{.ServerVersion}}'

If that prints a version, metralectl run will work. You do not need to restart the metralectl agent — it re-checks its own capability, so the control plane stops saying "this machine cannot run models" within a few seconds.

Do not use sudo metralectl

It appears to work, and it is the wrong move:

• the model runs as root, and so does everything the container does;
• the model cache it mounts is root's (/root/.cache/huggingface), or, when sudo keeps your HOME, files under your own cache end up owned by root, so the next unprivileged metralectl run fails in a way that looks unrelated;
• sudo uses root's PATH, so metralectl is frequently "not found" even though which metralectl finds it for you.

Fix the group membership instead. It is a one-time change.

Rootless Docker and Podman

If you run rootless Docker, the socket is under $XDG_RUNTIME_DIR rather than /var/run, and group membership is not the issue — check that DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock is exported. Docker's own post-installation guide is the canonical reference for both the group and the rootless setups.

Cannot connect to the Docker daemon

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Nothing is listening. Start it:

sudo systemctl start docker
sudo systemctl enable docker    # so it survives a reboot

docker: command not found

Docker is not installed, or not on this shell's PATH. metralectl list, metralectl show and metralectl run --print all work without a container engine — only metralectl run needs one. See Installation for the prerequisites, including the NVIDIA container runtime.

metralectl is not on PATH

The installer puts the binary in ~/.local/bin and tells you if that directory is not on your PATH. Add it:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc

Note the absence of a trailing slash. A PATH entry that ends in / is legal and works, but it makes which print a doubled slash — /home/you/.local/bin//metralectl — which looks like a bug and is not one: which joins the PATH entry to the program name without checking whether the entry already ends in a separator.

The control plane says this machine cannot run models

The browser is repeating what the local agent told it. The agent decides by running docker info, so the cause is almost always one of the Docker problems above — most often the permission one. Fix that and the page corrects itself within a few seconds; there is no need to restart the agent.

To see the agent's own view:

metralectl doctor

doctor reports each check and exits non-zero if any of them found a problem, so it is safe to use in a script.