Development Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mullvad/mullvadvpn-app/llms.txt

Use this file to discover all available pages before exploring further.

​

Build Issues

​

Cargo Build Failures

​

”failed to run custom build command”

sudo apt install gcc libdbus-1-dev protobuf-compiler libprotobuf-dev

sudo dnf install dbus-devel protobuf-devel

brew install protobuf

​

”could not find wintun.dll”

cp dist-assets/binaries/x86_64-pc-windows-msvc/wintun.dll target/debug/

​

Linker errors on Windows

1. Install Visual Studio 2022 Build Tools
2. Source the vcvars script:
   . ./scripts/vcvars.sh
   

​

Node/NPM Issues

​

”command not found: volta” or “wrong Node version”

curl https://get.volta.sh | bash
cd desktop
volta install node

brew install volta && volta setup
cd desktop
volta install node

​

”Cannot find module” or npm install fails

cd desktop
rm -rf node_modules package-lock.json
npm install -w mullvad-vpn

​

Cross-compilation Issues

​

ARM64 build fails on x64 Linux

# Install cross-compilation toolchain
sudo dpkg --add-architecture arm64
sudo apt update
sudo apt install libdbus-1-dev:arm64 gcc-aarch64-linux-gnu

# Add to ~/.cargo/config.toml
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

[target.aarch64-unknown-linux-gnu.dbus]
rustc-link-search = ["/usr/aarch64-linux-gnu/lib"]
rustc-link-lib = ["dbus-1"]

​

Runtime Issues

​

Daemon Won’t Start

​

”Permission denied” or “Address already in use”

sudo MULLVAD_RESOURCE_DIR="./dist-assets" ./target/debug/mullvad-daemon -vv

psexec64 -i -s bash.exe
./target/debug/mullvad-daemon.exe -vv

​

Daemon fails with “cannot connect to system service”

# Linux/macOS: Check socket exists
ls -la /var/run/mullvad-vpn

# Set custom socket path if needed
export MULLVAD_RPC_SOCKET_PATH="/path/to/socket"

​

GUI Issues

​

GUI shows “Lost contact with system service”

1. Check if daemon is running:
   # Linux
   systemctl status mullvad-daemon
   
   # macOS
   launchctl list | grep mullvad
   
   # Windows
   sc query mullvadvpn
   
2. Check daemon logs:
   • Linux/macOS: /var/log/mullvad-vpn/daemon.log
   • Windows: C:\ProgramData\Mullvad VPN\daemon.log
3. Restart the daemon

​

GUI won’t start in development mode

cd desktop/packages/mullvad-vpn
npm run develop

• Daemon not running
• Wrong MULLVAD_PATH environment variable
• Missing dependencies

​

Tunnel Issues

​

”Failed to set up tunnel” or connection timeouts

1. Enable verbose logging:
   sudo MULLVAD_RESOURCE_DIR="./dist-assets" ./target/debug/mullvad-daemon -vv
   
2. Check firewall isn’t blocking:
   # Linux
   sudo iptables -L -n
   
   # macOS  
   sudo pfctl -sr
   
3. Test API connectivity:
   mullvad status
   

​

macOS: Offline detection stuck

# Disable offline monitor
export TALPID_DISABLE_OFFLINE_MONITOR=1
sudo MULLVAD_RESOURCE_DIR="./dist-assets" ./target/debug/mullvad-daemon -vv

​

Platform-Specific Issues

​

Windows

​

”Failed to initialize split tunneling”

1. Check driver is loaded:
   sc query mullvadst
   
2. Reinstall the driver (requires admin):
   cd windows/split-tunnel
   .\install.bat
   

​

BSOD or driver crashes

• Windows version
• Driver version
• Crash dump

​

macOS

​

”Full Disk Access required” for split tunneling

1. Go to System Preferences → Security & Privacy → Privacy → Full Disk Access
2. Add mullvad-daemon
3. Restart the daemon

​

High CPU usage

1. Update to latest Electron version
2. Check for daemon log spam
3. Profile with Activity Monitor or Instruments

​

Linux

​

”Operation not permitted” with cgroups

# Check cgroup version
mount | grep cgroup

# For cgroup v2, set custom path if needed
export TALPID_CGROUP2_FS="/sys/fs/cgroup"

# For cgroup v1
export TALPID_NET_CLS_MOUNT_DIR="/sys/fs/cgroup/net_cls"

​

GUI crashes immediately on startup

# Install required icon themes
sudo apt install gnome-icon-theme

# Check AppArmor isn't blocking (Ubuntu 24.04+)
sudo aa-status | grep mullvad

​

Debugging Tools

​

Environment Variables

# Linux: Add packet counters
export TALPID_FIREWALL_DEBUG=1

# macOS: Log packets
export TALPID_FIREWALL_DEBUG=all  # or 'pass' or 'drop'

# Disable local DNS resolver (macOS)
export TALPID_DISABLE_LOCAL_DNS_RESOLVER=1

# Choose DNS configuration method
export TALPID_DNS_MODULE=systemd  # Linux: static-file, resolvconf, network-manager
export TALPID_DNS_MODULE=netsh    # Windows: iphlpapi, tcpip

# Force userspace WireGuard
export TALPID_FORCE_USERSPACE_WIREGUARD=1

export MULLVAD_API_HOST=api.mullvad.net
export MULLVAD_API_ADDR=10.10.1.2:443
export MULLVAD_CONNCHECK_HOST=am.i.mullvad.net

export MULLVAD_BACKTRACE_ON_FAULT=1

​

Logging

# -v: verbose, -vv: very verbose
mullvad-daemon -vv

• Linux/macOS: /var/log/mullvad-vpn/daemon.log
• Windows: %PROGRAMDATA%\Mullvad VPN\daemon.log

• Open DevTools in GUI (Ctrl+Shift+I / Cmd+Option+I)
• Check Console tab for JavaScript errors

​

Testing API Connectivity

# Check connection
curl -v https://api.mullvad.net/

# Test with custom host (dev builds)
MULLVAD_API_HOST=api.mullvad.net mullvad status

​

Capturing Network Traffic

# Capture on tunnel interface
sudo tcpdump -i wg0-mullvad -w capture.pcap

# Capture PF firewall logs
sudo tcpdump -i pflog0

# Capture on tunnel
sudo tcpdump -i utun3 -w capture.pcap

​

Getting Help

1. Check existing issues: GitHub Issues
2. Search discussions: GitHub Discussions
3. Read documentation: Check docs/ folder in repo
4. Report a bug: Include:
   • OS and version
   • Mullvad version
   • Steps to reproduce
   • Relevant logs
   • Expected vs actual behavior

​

Next Steps