Troubleshooting
Use the built-in status and logging commands to inspect both the macOS host side and the Linux guest.
Check overall state
Section titled “Check overall state”Run kat status to verify that the daemon, VM, Docker Engine, NFS mount, and port forwards are healthy:
kat statuskat status --jsonRead logs by component
Section titled “Read logs by component”katamaran separates logs into four streams:
kat logs --source daemon -n 200kat logs --source console -n 200kat logs --source vm -n 200kat logs --source gvproxy -n 200Add -f to follow any stream live. Inside the guest, containerd and dockerd also write to /var/log/containerd.log and /var/log/dockerd.log.
Measure boot stages
Section titled “Measure boot stages”If the VM starts slowly or fails during boot, run katamaran debug-boot to boot a throwaway VM and print per-stage timings:
katamaran debug-bootDocker commands cannot connect to the socket
Section titled “Docker commands cannot connect to the socket”- Confirm the VM is running with
kat status. - Verify which Docker context is active:
docker context ls- Switch to
katamaranif another context is selected:
docker context use katamaran- Check whether
DOCKER_HOSTis overriding the Docker context in your shell:
echo "$DOCKER_HOST"Unset DOCKER_HOST or point it to unix://$HOME/.katamaran/run/docker.sock.
Gatekeeper blocks a local build
Section titled “Gatekeeper blocks a local build”Unsigned builds made with cargo xtask app or cargo xtask dmg are ad-hoc signed. If macOS refuses to open Katamaran.app:
- Open System Settings.
- Select Privacy & Security.
- Click Open Anyway next to the Katamaran message.
~/Katamaran mount does not appear or is stale
Section titled “~/Katamaran mount does not appear or is stale”- Check whether
mountis enabled:
kat config get mountkat config get mount_path- Restart the VM to remount cleanly:
kat restart- If a previous crash left a stale NFS mount point, unmount it manually before starting again:
umount -f ~/KatamaranPublished or auto-forwarded port is unreachable
Section titled “Published or auto-forwarded port is unreachable”- Check that the service inside the container listens on
0.0.0.0or::, not only127.0.0.1. Automatic port forwarding and-ponly expose wildcard listeners. - Check whether another macOS process already holds the same port on
127.0.0.1:
lsof -nP -iTCP:<PORT> -sTCP:LISTEN- Verify the port appears in
kat statusand checkkat logs --source gvproxy.
Reset all VM data
Section titled “Reset all VM data”If the btrfs data disk becomes corrupted or you want a completely clean Docker and machine state:
- Stop the VM:
kat stop- Remove the data disk (this deletes all Docker images, containers, volumes, and Linux machines):
rm -f ~/.katamaran/data/data.img- Start the VM again. katamaran clones a fresh
data.imgon startup:
kat start