# Troubleshooting

Start here:

```bash
nodeau doctor
```

It is read-only and usually names the problem directly.

## `nodeau: command not found`

`~/.local/bin` is not on your `PATH`:

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

## The installer says my checksum does not match

It refused to install, which is correct. Usually an interrupted download — try
again. If it repeats, do not work around it; report it.

## `nvidia-smi` works but Nodeau says the GPU is unavailable

The driver is fine and the container path is not. Check:

```bash
nodeau doctor
```

If it reports the NVIDIA Container Toolkit missing, `nodeau install` installs
it — run that. If the toolkit is present but no CDI spec exists in `/etc/cdi`
or `/var/run/cdi`, a container cannot claim the GPU; `nodeau install` generates
one for you, and the equivalent by hand is:

```bash
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
```

## Nodeau refuses to deploy my model

That is the product working. Nodeau predicts peak VRAM before scheduling and
refuses what will not fit rather than letting it crash-loop.

```bash
nodeau service explain <name>
```

shows the whole calculation: what CUDA can address, what your desktop is using,
the safety reserve, and what the model needs. It also suggests remedies.

If it says it has **no validated profile** for your GPU, that is a limitation,
not a failure — Alpha ships one measured profile, and Nodeau will not invent
numbers for hardware nobody has measured.

## The endpoint disappeared after I logged out

Expected in Alpha. The local endpoint runs as a systemd **user** service, which
stops when your session ends. Log back in and:

```bash
nodeau run qwen-local
```

To keep it running across logout and at boot, enable lingering for your account
— this is a real change to session behaviour, which is why Nodeau does not do
it for you:

```bash
sudo loginctl enable-linger "$USER"
```

## Port 8080 is already in use

Nodeau detects the conflict and picks another port, then tells you which. To
choose one:

```bash
nodeau run qwen-local --port 8123
```

## Checking the endpoint is not exposed to my network

Reasonable thing to verify:

```bash
ss -tlnp | grep nodeau
```

The address must be `127.0.0.1:<port>`. If you ever see `0.0.0.0`, that is a
bug worth reporting immediately.

## Getting help

```bash
nodeau support bundle
```

Then email founders@nodeau.ai with the archive. It contains no keys, no
credentials, no prompts and no model output — and it is a plain tar.gz, so you
can check that yourself before sending.