# Debug a VM that will not come up

The question to settle first is whether the platform failed to build or start
the machine, which you can read, or whether the guest is refusing you, which
you cannot. In this order:

## 1. Did the create even succeed?

`POST /v1/vms` blocks until the machine is built, so a provisioning failure
came back on the create itself as `409 create_failed`, carrying the
hypervisor's own text, and the partial VM was destroyed and its IP released.
There is no half-built machine to inspect. Fix what `detail` said and create
again.

## 2. What does the platform think the machine is doing?

```
GET /v1/vms/{id}
```

Two separate fields, and there is no `state`:

- `status` is the platform's view of the record (`active`).
- `power` is read live from the hypervisor on every request — `running`,
  `stopped`, or `unknown`.

`power: "unknown"` with `health: "unreachable"` means the hypervisor could not
be reached. That is ours, not yours, and actions on that VM fail fast until it
clears. A VM that was running when the hypervisor under it rebooted comes back
up on its own.

If `power` is `stopped`, start it: creation leaves a machine stopped, and
starting it is a separate call.

## 3. What happened, in order?

```
GET /v1/vms/{id}/events
```

The newest 100 events for that VM, in order: what the platform did, when, and
what failed. This is where to look when a create or an action did not do what
you expected.

## 4. Is it running but unreachable?

If `power` is `running`, nothing on our side is left to check. Then:

- **The address.** Each machine carries its own `ip` in `GET /v1/vms`. A
  recreated VM has a **different** address — the old one went back to the
  pool. If you wrote an address down rather than putting a DNS name in front,
  this is usually it.
- **Your own firewall.** The only rule the platform enforces is anti-spoof.
  Nothing else inbound is filtered by us, so anything dropping your connection
  is running in your guest:
  [Firewall](../vm.md#firewall-one-platform-rule-the-rest-is-yours).
- **Your key.** The keys you passed at creation are the only way in. Log in as
  `ubuntu`.

## 5. If it is the guest, it is unrecoverable

There is no console, no password and no rescue mode, so a firewall or sshd
change that locks you out has no door behind it. Two ways out:

- **Roll back a snapshot**, if you took one before the change. It needs the VM
  stopped and leaves it stopped, and only the newest snapshot is restorable.
  See [Snapshots](../vm.md#snapshots).
- **[Recreate the VM](recreate-vm.md)** and re-run your configuration. Your
  volumes detach from the old machine and attach to the new one with their
  data intact; the root disk does not survive.

To not be here again, make every firewall and sshd change revert itself
unless you confirm it: [Harden a VM](harden-your-vm.md).