Skip to main content

Troubleshooting

Each section starts with what you see. If yours isn't here, run hb builder repair; it checks each piece in turn and suggests a next step.

"Apple container is not installed" during a switch​

HexBox couldn't find the container command. Install it (see Installation), then switch again.

If it is installed and HexBox still can't find it, it's probably somewhere the Nix daemon doesn't look. HexBox checks your PATH, /opt/homebrew/bin, /usr/local/bin, and your mise shims. With mise, make sure it's installed globally (mise use -g container). Otherwise, set containerBinary to the command's full path.

"could not create the builder's SSH keys" during a switch​

Each switch creates the builder's SSH keys if they're missing, and this one couldn't. Run the key script yourself to see the error:

~/.local/state/hb/bootstrap-keys.sh

The usual cause is that HexBox can't write to ~/.local/state/hb.

Builds fail with "platform mismatch" or "local builds are disabled"​

Nix couldn't use the builder, so it tried to build the Linux package on your Mac, which can't. Check the builder:

hb builder repair
hb builder test

If hb builder test passes but your own build still fails, check whether you used --rebuild or --check. Nix never sends those to a remote builder.

The builder never becomes reachable​

hb builder repair stops at "SSH handshake failed", or builds hang and then fail. Look at what the machine did as it started:

hb builder logs boot
hb builder logs readiness

Look for an image that failed to build or download, a machine that didn't finish booting, or SSH that never started. If you use a custom image, check that it includes socat, base64, getent, and /sbin/init.

Apple's container service is stuck​

Apple's container is a separate service, and it occasionally gets into a bad state that HexBox can't prevent. hb doctor runtime restarts it, and hb builder repair does the same before anything else. If neither helps, try container system stop and container system start yourself.

Downloads from cache.nixos.org fail​

The builder downloads prebuilt packages from https://cache.nixos.org/, so it needs working DNS and internet access. Run:

hb doctor dns

It checks whether the builder can reach common websites, and restarts Apple's container service if not. If it still fails, check your Mac's own network, VPN, or proxy settings.

Builds fail because pasta can't open /dev/net/tun​

Sandboxed builds use pasta for networking, which needs /dev/net/tun. The builder sets that up each time it boots. Run hb builder repair to restart it, then check from inside:

hb builder ssh getent group nixbld
hb builder ssh stat -c '%a %U:%G' /dev/net/tun

NixOS VM tests time out, or the builder's Nix daemon crashes​

On M1 and M2 Macs, VM tests run in slow software emulation, and several at once overload the builder. Set maxJobs to 1 or 2; see Configuration.

Everything the builder had built is gone​

The builder's /nix store survives stopping and starting. It's emptied when the machine is replaced: by hb builder reset, or by HexBox after you change the builder image. The next builds will download or rebuild what they need.

Containers can't reach host.container.internal​

HexBox sets up host.container.internal so Apple containers can reach services on your Mac. Check it, and recreate it if it's missing:

hb doctor host # can the name be found?
hb doctor host 8080 # can port 8080 on your Mac be reached?

The fix needs administrator rights, so it asks for your password. If you don't want the name at all, set exposeHostContainerInternal = false.