# Troubleshooting

Fix connection problems, read Kuvo's logs, and start over when you need to.

## Check the basics

```sh
kuvo status
```

If it says Kuvo is running, the engine is up and the socket path is printed. If the `docker` command still can't connect, it isn't pointed at Kuvo. Run:

```sh
eval "$(kuvo env)"
docker version
```

If `kuvo` itself isn't found, open Kuvo once and start a new terminal window. See [The kuvo command](/docs/installation/#the-kuvo-command).

## Cannot connect to the Docker daemon

The docker command is talking to a different socket. Common causes:

- `DOCKER_HOST` isn't set in this shell. Run `eval "$(kuvo env)"` or add it to `~/.zshrc`.
- A Docker context points elsewhere. Run `docker context ls`. If you created a `kuvo` context, `docker context use kuvo`.
- Kuvo isn't open. Open it, or run any `kuvo` command, which starts it.

## A port is already in use

Kuvo forwards each published port to `localhost`. If another program already uses that port, including Docker Desktop, the forward can't open. Quit the other program, or publish on a different port: `-p 8081:80`.

## Intel images fail with "exec format error"

Rosetta isn't installed. Install it and restart Kuvo:

```sh
softwareupdate --install-rosetta --agree-to-license
```

## Bind mounts are empty

Only `/Users` is shared with the VM. A path like `/tmp/project` or `/opt/data` doesn't exist inside it. Move the folder into your home directory.

## The engine doesn't start

The window shows what went wrong, with a **Try Again** button. Kuvo keeps two logs that usually explain it:

| File | What's in it |
| --- | --- |
| `~/Library/Application Support/Kuvo/console.log` | The VM's boot output: kernel, setup steps and errors. |
| `~/Library/Application Support/Kuvo/share/docker.log` | Docker's own log from inside the VM. |

```sh
tail -n 50 ~/Library/Application\ Support/Kuvo/console.log
tail -n 50 ~/Library/Application\ Support/Kuvo/share/docker.log
```

Some common causes:

- **First launch fails while downloading.** Kuvo needs to reach `dl-cdn.alpinelinux.org` the first time. Check your connection, VPN or firewall and try again.
- **Right after quitting.** The VM's disk can stay locked for a moment after Kuvo quits. Kuvo retries for a few seconds; if it still fails, wait and click **Try Again**.
- **The disk is full.** Free up space on your Mac, or clean up inside Docker with `docker system prune`.

## Start over

To reset Kuvo's VM while keeping the app, quit Kuvo, then delete its disk:

```sh
rm ~/Library/Application\ Support/Kuvo/disk.img
```

The next launch sets the VM up again from scratch. This **deletes all images, containers and volumes** in Kuvo.

## Report a problem

[Open an issue on GitHub](https://github.com/serhatandic/kuvo/issues) with:

- your macOS version and Mac model,
- the output of `kuvo status`,
- the last lines of `console.log` and `docker.log`.

Look through the logs before attaching them. They can include container names and paths from your Mac.