Skip to content

Troubleshooting

Use the built-in status and logging commands to inspect both the macOS host side and the Linux guest.

Run kat status to verify that the daemon, VM, Docker Engine, NFS mount, and port forwards are healthy:

Terminal window
kat status
kat status --json

katamaran separates logs into four streams:

Terminal window
kat logs --source daemon -n 200
kat logs --source console -n 200
kat logs --source vm -n 200
kat logs --source gvproxy -n 200

Add -f to follow any stream live. Inside the guest, containerd and dockerd also write to /var/log/containerd.log and /var/log/dockerd.log.

If the VM starts slowly or fails during boot, run katamaran debug-boot to boot a throwaway VM and print per-stage timings:

Terminal window
katamaran debug-boot

Docker commands cannot connect to the socket

Section titled “Docker commands cannot connect to the socket”
  1. Confirm the VM is running with kat status.
  2. Verify which Docker context is active:
Terminal window
docker context ls
  1. Switch to katamaran if another context is selected:
Terminal window
docker context use katamaran
  1. Check whether DOCKER_HOST is overriding the Docker context in your shell:
Terminal window
echo "$DOCKER_HOST"

Unset DOCKER_HOST or point it to unix://$HOME/.katamaran/run/docker.sock.

Unsigned builds made with cargo xtask app or cargo xtask dmg are ad-hoc signed. If macOS refuses to open Katamaran.app:

  1. Open System Settings.
  2. Select Privacy & Security.
  3. 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”
  1. Check whether mount is enabled:
Terminal window
kat config get mount
kat config get mount_path
  1. Restart the VM to remount cleanly:
Terminal window
kat restart
  1. If a previous crash left a stale NFS mount point, unmount it manually before starting again:
Terminal window
umount -f ~/Katamaran

Published or auto-forwarded port is unreachable

Section titled “Published or auto-forwarded port is unreachable”
  1. Check that the service inside the container listens on 0.0.0.0 or ::, not only 127.0.0.1. Automatic port forwarding and -p only expose wildcard listeners.
  2. Check whether another macOS process already holds the same port on 127.0.0.1:
Terminal window
lsof -nP -iTCP:<PORT> -sTCP:LISTEN
  1. Verify the port appears in kat status and check kat logs --source gvproxy.

If the btrfs data disk becomes corrupted or you want a completely clean Docker and machine state:

  1. Stop the VM:
Terminal window
kat stop
  1. Remove the data disk (this deletes all Docker images, containers, volumes, and Linux machines):
Terminal window
rm -f ~/.katamaran/data/data.img
  1. Start the VM again. katamaran clones a fresh data.img on startup:
Terminal window
kat start