{"record":{"id":"1c4f87d64a76eb03","repo":"firecracker-microvm/firecracker","slug":"gdb-requires-kvm-1c4f87","errorCode":null,"errorMessage":"GDB requires KVM","messagePattern":"GDB requires KVM","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/vmm/src/gdb/mod.rs","lineNumber":47,"sourceCode":"///\n/// This will then create the GDB socket which will be used for communication to the GDB process.\n/// After creating this, the function will block while waiting for GDB to connect.\n///\n/// After the connection has been established the function will start a new thread for handling\n/// communcation to the GDB server\npub fn gdb_thread(\n    vmm: Arc<Mutex<Vmm>>,\n    gdb_event_receiver: Receiver<usize>,\n    entry_addr: GuestAddress,\n    socket_addr: &str,\n) -> Result<(), GdbTargetError> {\n    // We register a hw breakpoint at the entry point as GDB expects the application\n    // to be stopped as it connects. This also allows us to set breakpoints before kernel starts.\n    // This entry adddress is automatically used as it is not tracked inside the target state, so\n    // when resumed will be removed\n    {\n        let vmm = vmm.lock().unwrap();\n        let kvm_vm = vmm.vm.as_kvm().expect(\"GDB requires KVM\");\n        let handles = kvm_vm.vcpus_handles();\n        vcpu_set_debug(&handles[0].vcpu_fd, &[entry_addr], false)?;\n        for handle in &handles[1..] {\n            vcpu_set_debug(&handle.vcpu_fd, &[], false)?;\n        }\n    }\n\n    let path = Path::new(socket_addr);\n    let listener = UnixListener::bind(path).map_err(GdbTargetError::ServerSocketError)?;\n    trace!(\"Waiting for GDB server connection on {}...\", path.display());\n    let (connection, _addr) = listener\n        .accept()\n        .map_err(GdbTargetError::ServerSocketError)?;\n\n    std::thread::Builder::new()\n        .name(\"gdb\".into())\n        .spawn(move || event_loop(connection, vmm, gdb_event_receiver, entry_addr))\n        .map_err(|_| GdbTargetError::GdbThreadError)?;","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/firecracker-microvm/firecracker/blob/0a745def42ddf4cc2a744d79a08a27ff50b5d27a/src/vmm/src/gdb/mod.rs#L29-L65","documentation":"`expect(\"GDB requires KVM\")` at the top of `gdb_thread` (mod.rs:47): before serving any GDB connection, the stub locks the Vmm and calls `vmm.vm.as_kvm()` to obtain vcpu fds for installing the entry hardware breakpoint. If the VM is not KVM-backed, as_kvm() is None and the thread panics.","triggerScenarios":"Starting the GDB thread (`gdb_thread(...)`) against a Vmm constructed with a non-KVM backend — the breakpoint-install step `vcpu_set_debug(&handles[0].vcpu_fd, &[entry_addr], false)` needs real KVM vcpu fds and there is no fallback.","commonSituations":"GDB/debug feature enabled in a build or test environment where the VM runs without KVM (mock vm in tests, alternate hypervisor backend, /dev/kvm absent so a degraded config was picked).","solutions":["Verify KVM is available and used before spawning the gdb thread: check `vmm.vm.as_kvm().is_some()` and return an error like RequiresKvm otherwise","Ensure /dev/kvm is present and the user has rw access (kvm group)","Skip enabling the GDB feature on non-KVM deployments"],"exampleFix":"// before\nlet kvm_vm = vmm.vm.as_kvm().expect(\"GDB requires KVM\");\n\n// after\nlet kvm_vm = vmm\n    .vm\n    .as_kvm()\n    .ok_or(GdbTargetError::RequiresKvm)?;","handlingStrategy":"validation","validationCode":"// Pre-flight the gdb thread\nlet kvm_ok = vmm.lock().unwrap().vm.as_kvm().is_some();\nif !kvm_ok {\n    return Err(GdbTargetError::RequiresKvm); // instead of spawning gdb_thread\n}","typeGuard":"fn gdb_supported(vmm: &Arc<Mutex<Vmm>>) -> bool {\n    vmm.lock().unwrap().vm.as_kvm().is_some()\n}","tryCatchPattern":null,"preventionTips":["Gate the --gdb flag on KVM detection at CLI parsing time","Keep gdb and non-KVM backend features mutually exclusive in the build matrix","Surface RequiresKvm as a config validation error, not a runtime panic"],"tags":["rust","panic","gdb","kvm","breakpoint","firecracker"],"backgroundTag":"kvm-backend-unavailable","analyzedSha":"0a745def42ddf4cc2a744d79a08a27ff50b5d27a","analyzedAt":"2026-08-19T05:27:02.517Z","contentChangedAt":"2026-08-19T05:27:02.517Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}