{"record":{"id":"7fb7875446cb4195","repo":"hashicorp/vagrant","slug":"the-guest-machine-entered-an-invalid-state-while-w","errorCode":null,"errorMessage":"The guest machine entered an invalid state while waiting for it to boot. Valid states are '%{valid}'. The machine is in the '%{invalid}' state. Please verify everything is configured properly and try again.\n\nIf the provider you're using has a GUI that comes with it, it is often helpful to open that and watch the machine, since the GUI often has more helpful error messages than Vagrant can retrieve. For example, if you're using VirtualBox, run `vagrant up` while the VirtualBox GUI is open.\n\nThe primary issue for this error is that the provider you're using is not properly configured. This is very rarely a Vagrant issue.","messagePattern":"The guest machine entered an invalid state while waiting for it to boot\\. Valid states are '%\\{valid\\}'\\. The machine is in the '%\\{invalid\\}' state\\. Please verify everything is configured properly and try again\\.\n\nIf the provider you're using has a GUI that comes with it, it is often helpful to open that and watch the machine, since the GUI often has more helpful error messages than Vagrant can retrieve\\. For example, if you're using VirtualBox, run `vagrant up` while the VirtualBox GUI is open\\.\n\nThe primary issue for this error is that the provider you're using is not properly configured\\. This is very rarely a Vagrant issue\\.","errorType":"exception","errorClass":"Vagrant::Errors::VMBootBadState","httpStatus":null,"severity":"error","filePath":"lib/vagrant/action/builtin/wait_for_communicator.rb","lineNumber":58,"sourceCode":"              # Sleep a bit so we don't hit 100% CPU constantly.\n              sleep 1\n            end\n          end\n\n          # Wait for a result or an interrupt\n          env[:ui].output(I18n.t(\"vagrant.boot_waiting\"))\n          while ready_thr.alive? && states_thr.alive?\n            sleep 1\n            return if env[:interrupted]\n          end\n\n          # Join so that they can raise exceptions if there were any\n          ready_thr.join if !ready_thr.alive?\n          states_thr.join if !states_thr.alive?\n\n          # If it went into a bad state, then raise an error\n          if !states_thr[:result]\n            raise Errors::VMBootBadState,\n              valid: @states.join(\", \"),\n              invalid: states_thr[:last_known_state]\n          end\n\n          # If it didn't boot, raise an error\n          if !ready_thr[:result]\n            raise Errors::VMBootTimeout\n          end\n\n          env[:ui].output(I18n.t(\"vagrant.boot_completed\"))\n\n          # Make sure our threads are all killed\n          ready_thr.kill\n          states_thr.kill\n\n          @app.call(env)\n        ensure\n          ready_thr.kill","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/action/builtin/wait_for_communicator.rb#L40-L76","documentation":"While waiting for the communicator, WaitForCommunicator polls machine.state.id in a side thread against the provider's list of acceptable boot states (@states, e.g. ['starting','running'] for VirtualBox). If the VM leaves that state set — crashed to 'aborted', VirtualBox 'gurumeditation', 'paused'/'saved' — the states thread sets result=false and VMBootBadState is raised with the valid states and the last observed invalid one.","triggerScenarios":"`vagrant up` when the VM dies mid-boot: kernel panic, VirtualBox guru meditation (VT-x disabled, out of memory), host suspend pausing/saving the VM, provider reporting any state outside @states while wait_for_ready is still looping (lib/vagrant/action/builtin/wait_for_communicator.rb:24-42, 56-61).","commonSituations":"VirtualBox with VT-x/Nested Virtualization disabled in BIOS or hypervisor; VM RAM larger than available host memory; laptop sleep suspending hosts mid-boot; corrupted VM state after a hard host shutdown.","solutions":["Run `vagrant up` with the provider GUI open (e.g. the VirtualBox GUI) — as the message suggests, it usually shows the real error (VT-x, disk, boot failure).","Enable hardware virtualization (VT-x/AMD-V, nested virt) in BIOS/host hypervisor settings.","Reduce VM memory (`vb.memory = 2048`) or free host RAM; verify with `vagrant status` what state it landed in.","For a wedged VM: `vagrant halt && vagrant up`, or as last resort `vagrant destroy && vagrant up`; disable host auto-sleep for long builds."],"exampleFix":"# before\nconfig.vm.provider \"virtualbox\" do |vb|\n  vb.memory = 8192   # host OOM => VM aborts during boot\nend\n\n# after\nconfig.vm.provider \"virtualbox\" do |vb|\n  vb.memory = 2048\nend","handlingStrategy":"try-catch","validationCode":"# Shell: pre-flight the usual VirtualBox causes\n[ \"$(systemd-detect-virt 2>/dev/null)\" != \"none\" ] || grep -qm1 vmx /proc/cpuinfo || echo \"warning: VT-x not exposed to this host\"\ngrep -q 'memory' Vagrantfile && free -g | awk '/Mem:/{if ($2 < 2) print \"warning: low host RAM\"}'","typeGuard":null,"tryCatchPattern":"# Ruby: surface the bad state and recover once\nbegin\n  machine.action(\"up\")\nrescue Vagrant::Errors::VMBootBadState => e\n  warn \"VM entered invalid state '#{e.data[:invalid]}' (expected #{e.data[:valid]})\"\n  machine.action(\"halt\")\n  machine.action(\"up\")  # single retry; escalate to destroy if it repeats\nend","preventionTips":["Enable VT-x/AMD-V (and nested virtualization when Vagrant itself runs under a hypervisor) before headless boots.","Size vb.memory realistically against host RAM and disable host sleep during long builds.","On first mysterious boot failures, run `vagrant up` with the provider GUI open — providers usually print the real fault there."],"tags":["vagrant","boot","virtualbox","vm-state","timeout"],"backgroundTag":"vm-boot-failure","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}