# Troubleshoot instance issues

> Diagnose and resolve common CubeCOS instance problems, including launch failures, stuck states, console access, and resize or migration errors.

Use this guide to diagnose common problems with CubeCOS instances (virtual machines). If you haven't already, start with the [Troubleshooting overview](./overview) to rule out a cluster-wide issue.

## Before you begin {#before-you-begin}

Some checks require the OpenStack CLI. Run these commands from a controller node, or from any host with `/etc/admin-openrc.sh` sourced and the `openstack` client installed.

## An instance fails to launch {#an-instance-fails-to-launch}

1. Check the instance status and failure reason.

   ```bash title="Check the instance status and fault reason"
   openstack server show <instance-id> -c status -c fault
   ```

2. Open **Compute > Instances**, select the instance, and review the **Action Logs** tab for the failed event.

3. Check the following common causes:
   - The project's compute or volume quota is exhausted.
   - The source image or bootable volume isn't in `Active` status.
   - No host in the availability zone has enough free vCPU, memory, or disk to fit the flavor.
   - The selected network or security group no longer exists.

## An instance is stuck in Build status {#an-instance-is-stuck-in-build-status}

1. Confirm that the Compute service is healthy.

   ```bash title="Check cluster service health"
   controller> cluster check_repair
   ```

   Look for a `FIXING` status on the `Compute` row.

2. If you launched the instance from an image, confirm that the image finished uploading and shows `Active` status under **Compute > Images**. An image stuck in `Saving` status with a file size of `0` usually means two identical uploads ran at the same time.

3. Review the **Action Logs** tab on the instance for the specific scheduling or provisioning error.

## An instance won't stop or shows the wrong status {#an-instance-wont-stop-or-shows-the-wrong-status}

Check the server state and the compute host it's scheduled on.

```bash title="Check server state and host"
openstack server show <instance-id> -c status -c vm_state -c OS-EXT-SRV-ATTR:host
```

If `status` and `vm_state` disagree, or the reported host is unreachable, run `cluster check_repair` and check the `Compute` row before retrying the stop or start action.

## The console doesn't load {#the-console-doesnt-load}

1. Confirm that the instance status is `Active`. A console isn't available for a stopped or errored instance.
2. Reopen the console: navigate to **Compute > Instances**, click **CONSOLE** for the instance, then **Confirm**. For the full procedure, see [Connecting to your Linux or Windows instance](../compute/novnc_console.md).
3. If the console still fails to open, run `cluster check_repair` and check the `Compute` row for a `FIXING` status.

## Resizing or migrating an instance fails {#resizing-or-migrating-an-instance-fails}

1. Confirm the instance status is `Active` before you start. Resize and live migration both require the instance to be running normally.
2. After changing the flavor, confirm that you completed the **Confirm Resize or Migrate** step from the **More > Configuration Update** menu. A resize that isn't confirmed stays in a pending state.
3. Confirm that a destination host has enough free capacity for the new flavor.
4. Run `cluster check_repair` and check the `Compute` row for a `FIXING` status.

For the full procedure, see [Resize Instance](../compute/instance_resize.md).

## An instance has no network connectivity {#an-instance-has-no-network-connectivity}

Network connectivity problems are usually caused by the network configuration rather than the instance itself. See [Troubleshoot network issues](./network).

## A volume won't attach to or detach from an instance {#a-volume-wont-attach-to-or-detach-from-an-instance}

Volume attachment problems are usually caused by the volume or storage cluster state rather than the instance itself. See [Troubleshoot storage issues](./storage).