​

Troubleshooting

​

Daemon Issues

​

Daemon Not Running

Error: Failed to connect to daemon

# Check status
sudo systemctl status hyprd

# Start daemon
sudo systemctl start hyprd

# View logs
journalctl -u hyprd -f

# Check status
sudo launchctl list | grep hypr

# Load daemon
sudo launchctl load /Library/LaunchDaemons/ai.hypr.hyprd.plist

# View logs
tail -f /var/log/hypr/hyprd.log

​

Another Instance Running

Another hyprd instance is already running (PID 12345)

# Kill existing process
sudo kill 12345

# Remove stale PID file
sudo rm /run/hypr/hyprd.pid  # Linux
sudo rm /tmp/hypr/hyprd.pid  # macOS

# Start daemon
sudo systemctl start hyprd   # Linux
sudo launchctl load /Library/LaunchDaemons/ai.hypr.hyprd.plist  # macOS

​

Permission Denied

Error: Permission denied: /var/lib/hypr

# Linux
sudo systemctl restart hyprd

# macOS - ensure running as root
sudo launchctl kickstart -k system/ai.hypr.hyprd

​

VM Issues

​

VM Fails to Start

Error: Failed to start VM: hypervisor error

1. Missing kernel:
   Copy

   ls /var/lib/hypr/vmlinux
   
   If missing, delete and let HYPR re-download:
   Copy

   sudo rm /var/lib/hypr/vmlinux
   hypr run nginx  # triggers download
   
2. KVM not available (Linux):
   Copy

   ls /dev/kvm
   
   If missing, enable virtualization in BIOS or install KVM:
   Copy

   sudo apt install qemu-kvm  # Debian/Ubuntu
   
3. Hypervisor library not found (macOS): Check if libkrun-efi is installed:
   Copy

   ls /opt/homebrew/opt/libkrun-efi/lib/libkrun-efi.dylib  # ARM64
   ls /usr/local/opt/libkrun-efi/lib/libkrun-efi.dylib     # Intel
   
   Install if missing:
   Copy

   brew tap slp/krunkit && brew install libkrun-efi
   

​

VM Boot Timeout

Error: VM health check timeout

1. Image entrypoint fails immediately:
   Copy

   hypr logs <vm-id>
   
   Check for application errors.
2. Resource constraints: Increase memory:
   Copy

   hypr run <image> -m 1024
   
3. Slow disk I/O: Wait longer or check disk health.

​

Cannot Connect to VM Port

1. VM running:
   Copy

   hypr ps
   
2. Port mapping correct:
   Copy

   hypr ps | grep <vm-id>
   # Check PORTS column
   
3. Service running in VM:
   Copy

   hypr exec <vm-id> -- ss -tlnp
   
4. Firewall blocking:
   Copy

   # Linux
   sudo iptables -L -n | grep <port>
   
   # macOS
   sudo pfctl -sr | grep <port>
   

​

Image Issues

​

Image Pull Failed

Error: Failed to pull image: connection refused

1. Network connectivity:
   Copy

   curl -I https://registry-1.docker.io/v2/
   
2. DNS resolution:
   Copy

   nslookup registry-1.docker.io
   
3. Proxy settings: If behind corporate proxy, set HTTP_PROXY and HTTPS_PROXY.

​

Image Not Found

Error: Image not found: myimage:latest

1. Correct image name:
   Copy

   # Docker Hub library images
   hypr pull nginx           # correct
   hypr pull library/nginx   # also correct
   
   # User images
   hypr pull user/repo:tag
   
   # Other registries
   hypr pull ghcr.io/org/repo:tag
   
2. Tag exists: Check registry for available tags.
3. Architecture match: Some images only have x86_64 or ARM64 variants.

​

Build Failed

Error: Build failed: instruction failed

1. View build output: Build errors are printed to stdout.
2. Missing dependencies: Add required packages in Dockerfile:
   Copy

   RUN apt-get update && apt-get install -y <package>
   
3. Network in build: Build VMs have no network access. All downloads must happen in the base image or use multi-stage builds.
4. Check Dockerfile syntax:
   Copy

   # Validate with Docker (if available)
   docker build --check .
   

​

Network Issues

​

No Network in VM

1. Bridge exists:
   Copy

   ip link show vbr0
   
2. TAP attached:
   Copy

   ip link show master vbr0
   
3. IP forwarding enabled:
   Copy

   cat /proc/sys/net/ipv4/ip_forward
   # Should be 1
   
   Enable:
   Copy

   sudo sysctl -w net.ipv4.ip_forward=1
   
4. NAT configured:
   Copy

   sudo iptables -t nat -L POSTROUTING
   

1. vmnet service running: Check System Preferences > Sharing > Internet Sharing.
2. libkrun permissions: May need to allow in Security & Privacy settings.

​

DNS Not Resolving

hypr exec <vm-id> -- cat /etc/resolv.conf
hypr exec <vm-id> -- ping 8.8.8.8     # Check IP connectivity
hypr exec <vm-id> -- nslookup google.com

hypr exec <vm-id> -- sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

​

VMs Cannot Communicate

1. Same network: Ensure both VMs are on the same network (default or custom).
2. IP addresses:
   Copy

   hypr ps  # Shows IP column
   
3. Test connectivity:
   Copy

   hypr exec vm1 -- ping <vm2-ip>
   

​

Custom Network Not Working

1. Network exists:
   Copy

   hypr network ls
   
2. Network configuration:
   Copy

   hypr network inspect mynet
   
3. VMs attached: Check compose file has correct networks: section.

​

Volume Issues

​

Volume Not Found

Error: Volume 'mydata' not found

1. List volumes:
   Copy

   hypr volume ls
   
2. Check name: Stack volumes are prefixed: <stack>_<volume>
3. Check path:
   Copy

   ls /var/lib/hypr/volumes/
   

​

Volume In Use

Error: Volume 'mydata' is in use by: myvm

1. Stop the VM:
   Copy

   hypr stop myvm
   hypr volume rm mydata
   
2. Or force remove:
   Copy

   hypr volume rm mydata --force
   

​

Permission Denied on Volume

1. Host permissions:
   Copy

   ls -la /var/lib/hypr/volumes/local/mydata
   
2. Change permissions:
   Copy

   sudo chmod -R 777 /var/lib/hypr/volumes/local/mydata
   

​

GPU Issues

​

GPU Not Detected (Linux)

hypr gpu list
# No GPUs detected

1. GPU present:
   Copy

   lspci | grep -i vga
   lspci | grep -i nvidia
   
2. IOMMU enabled:
   Copy

   dmesg | grep -i iommu
   
   Add to kernel cmdline:
   • Intel: intel_iommu=on
   • AMD: amd_iommu=on
3. VFIO modules:
   Copy

   lsmod | grep vfio
   
   Load:
   Copy

   sudo modprobe vfio-pci
   

​

GPU Passthrough Failed

Error: GPU not bound to vfio-pci driver

1. Unbind from current driver:
   Copy

   echo "0000:01:00.0" | sudo tee /sys/bus/pci/drivers/nvidia/unbind
   
2. Bind to vfio-pci:
   Copy

   echo "10de 2684" | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id
   echo "0000:01:00.0" | sudo tee /sys/bus/pci/drivers/vfio-pci/bind
   

​

Metal Not Available (macOS)

1. macOS version: Requires macOS 14 (Sonoma) or later.
2. libkrun-efi version:
   Copy

   brew info libkrun-efi
   
   Update: brew upgrade libkrun-efi

​

Compose Issues

​

Stack Deploy Failed

Error: Failed to deploy stack

1. Compose file syntax:
   Copy

   # Validate with Docker (if available)
   docker compose config
   
2. Image availability:
   Copy

   hypr pull <image>
   
3. Port conflicts: Check if ports are already in use.

​

Service Dependency Timeout

hypr compose ps mystack
hypr logs <service-vm-id>

​

Volumes Not Created

1. Volume defined: Ensure volume is in top-level volumes: section.
2. Check volume:
   Copy

   hypr volume ls
   

​

Disk Space Issues

​

No Space Left

Error: No space left on device

1. Check usage:
   Copy

   hypr system df
   
2. Prune unused resources:
   Copy

   hypr system prune --all
   
3. Prune volumes:
   Copy

   hypr volume prune
   
4. Remove specific images:
   Copy

   hypr images
   hypr rmi <image>
   

​

Debug Mode

# Full debug
RUST_LOG=debug hyprd

# Component-specific
RUST_LOG=hypr_core::adapters=trace hyprd
RUST_LOG=hypr_daemon::network_manager=debug hyprd
RUST_LOG=hypr_core::network=debug hyprd

​

Getting Help

1. Check logs: journalctl -u hyprd -f (Linux) or tail -f /var/log/hypr/hyprd.log (macOS)
2. Enable debug logging: RUST_LOG=debug
3. Check system resources: hypr system df
4. Report issues: https://github.com/hyprhq/hypr/issues

​

Common Error Messages