Troubleshooting

This page lists common issues and their solutions when working with macpine.

Stale PID File

Symptom: alpine list reports an instance as Running, but it is not. Attempts to stop or delete it might fail.

Cause: The QEMU process was terminated unexpectedly (e.g., kill -9, system crash), leaving behind a PID file (alpine.pid).

Solution: Manually delete the PID file from the instance's directory.

rm ~/.macpine/your-instance-name/alpine.pid

To be certain no QEMU processes are running, you can use killall qemu-system-aarch64 or killall qemu-system-x86_64.

Inaccessible Instance

Symptom: You cannot SSH into your instance or it fails to start properly.

Cause: This often happens if the SSH server configuration inside the VM is changed incorrectly.

Solution:

• Ensure PermitRootLogin yes (or prohibit-password if using SSH keys) is set in /etc/ssh/sshd_config inside the VM.
• If you changed the root password inside the VM, you must update the rootpassword field in the instance's config.yaml to match. Use alpine edit your-instance-name to do this.

Time Drift

Symptom: The clock inside the VM is incorrect, especially after the host machine has been asleep.

Cause: When the host sleeps, the VM's clock stops ticking.

Solution:

1. Manual Sync: Run hwclock -s to sync the hardware clock from the host. You can do this from outside the VM:

   alpine exec your-instance-name "hwclock -s"

2. Automatic Sync (Recommended): Install an NTP client inside the VM to keep the time synchronized automatically.

   # Connect to the VM
   alpine ssh your-instance-name
   
   # Install and enable an NTP client (e.g., chrony)
   apk update && apk add chrony
   rc-update add chronyd default
   rc-service chronyd start

Networking Issues

• ping doesn't work: In the default SLIRP networking mode, ICMP traffic (used by ping) is not forwarded. This is expected behavior. Network connectivity for TCP/UDP should still work.
• Port conflict on start: If an instance fails to start with a port-related error, it means another service (or another macpine instance) is already using that port on your host. Ensure that the SSH port and any other forwarded ports are unique for each simultaneously running instance.
• Firewall Prompts: When you start an instance with port forwarding, macOS may ask if you want to allow incoming connections to qemu-system-*. You can typically click "Deny". Port forwarding from localhost (your host machine to the guest) will still work. If you need other machines on your network to access the forwarded ports, you must enable a host firewall and configure it appropriately.

Disk Resize Failure

Symptom: alpine launch fails with unable to resize disk: signal: abort trap.

Cause: This can be caused by a dynamic library issue with the qemu-img utility, often related to the gettext dependency installed via Homebrew.

Solution: Reinstall gettext using Homebrew.

brew reinstall gettext