Fail Fast When KVM Is Unavailable

When QEMU cannot access the host's KVM (Linux) or HVF (macOS) accelerator, it silently falls back to the TCG interpreter. Tests still pass, but they run roughly an order of magnitude slower. The only hint in the output is a QEMU log line buried between other driver messages.

Why This Matters

• Silent TCG fallback can turn a 2-minute test into a 20-minute test.
• Suddenly-slow CI runs are often misattributed to the code under test rather than to a host reconfiguration.
• Longer runs collide with globalTimeout and mask real regressions.

A missing accelerator is almost always a host-level problem (wrong group membership, virtualization disabled in BIOS, nested-virt not available in a CI runner). It is far more useful to surface this as an explicit test failure than to pay the price on every run.

Use qemu.forceAccel

Set qemu.forceAccel = true; at the top level of your test. If neither KVM (Linux) nor HVF (macOS) is available at runtime, the test aborts immediately with an actionable error message.

test.nix

{
  name = "example-test";

  qemu.forceAccel = true;

  nodes.machine = { ... }: {
    # configuration
  };

  testScript = ''
    start_all()
  '';
}

Typical error message when the option trips:

forceAccel is enabled but /dev/kvm is not accessible (permission denied).
Check that your user is in the 'kvm' group or that /dev/kvm has the correct permissions.

When to Use It

• CI

  ---

  Always enable qemu.forceAccel in CI. A silent TCG fallback there is essentially a hidden bug in the runner configuration.

• Local development

  ---

  Enable it whenever you rely on KVM being present. You will notice host-level regressions (group membership lost after a rebuild, device permissions changed) immediately, instead of chasing phantom slowdowns.

See also: Testing host setup — Linux KVM.