> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperbolic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the most common issues with GPU instances, connections, storage, and billing

Start here when something isn't working. Each section covers the quick fixes first and links to the detailed guide.

## Connection issues

<AccordionGroup>
  <Accordion title="Can't connect via SSH">
    1. Confirm the instance is in the **Ready** state — SSH is only available once provisioning completes.
    2. Copy the exact SSH command from your **Active Instances** page rather than constructing it by hand.
    3. Verify you're using the **private key** matching the public key on your account, with correct permissions (`chmod 600 ~/.ssh/your_key`).
    4. Run with `ssh -v` and include the output if you contact support.

    More detail: [On-Demand Quickstart — troubleshooting](/docs/on-demand/quickstart).
  </Accordion>

  <Accordion title="Connection drops or is slow">
    * Use `tmux` or `screen` so sessions survive disconnects.
    * Long-running jobs should never depend on an open SSH session — run them under `nohup`, `tmux`, or a process manager.
  </Accordion>
</AccordionGroup>

## Instance issues

<AccordionGroup>
  <Accordion title="Instance stuck in a pending/provisioning state">
    Provisioning normally completes in minutes. If an instance is pending for more than 30 minutes, contact [support](/docs/general/support) with the instance ID. Instances that never become ready are automatically terminated at the provisioning timeout (\~3 hours) and are **never charged** — see [Pricing](/docs/on-demand/pricing).
  </Accordion>

  <Accordion title="nvidia-smi shows no GPUs">
    GPU drivers are preinstalled on all instances. **Do not install or upgrade drivers yourself** — contact [support](/docs/general/support) with the instance ID and the `nvidia-smi` output.
  </Accordion>

  <Accordion title="Instance terminated unexpectedly">
    The two common causes:

    * **Balance reached zero.** Instances are automatically terminated when your account balance is no longer positive. Configure [Auto Top-Up](/docs/general/auto-top-up) to prevent this. Note the 30-day grace period to recover data on storage volumes.
    * **Reservation ended.** Reserved instances are automatically terminated at the end of the reservation period — see [Pricing](/docs/on-demand/pricing#reserved).

    On-machine data is not recoverable after termination; data on attached storage volumes survives.
  </Accordion>

  <Accordion title="Performance is lower than expected">
    Run the checks in [Verifying Instance Performance](/docs/on-demand/verifying-performance) — they'll either identify the bottleneck or give you the outputs support needs to investigate.
  </Accordion>

  <Accordion title="Instance states reference">
    See [Managing Instances](/docs/on-demand/managing-instances) for the full lifecycle of instance states and what each one means.
  </Accordion>
</AccordionGroup>

## Storage and networking

<AccordionGroup>
  <Accordion title="Out of disk space">
    Check usage with `df -h`. Onboard NVMe is fixed per configuration; attach a persistent storage volume for more space, or clean caches (`~/.cache`, old checkpoints, unused Docker images: `docker system prune`). Details: [Storage and Ports](/docs/on-demand/storage-and-ports).
  </Accordion>

  <Accordion title="Can't reach a service running on my instance">
    Confirm the port is exposed in your instance's port configuration and the service is bound to `0.0.0.0` rather than `localhost`. See [Storage and Ports](/docs/on-demand/storage-and-ports) for port setup and [Securing Open Ports](/docs/securing-open-ports) before exposing anything publicly.
  </Accordion>

  <Accordion title="Storage volume issues">
    Attachment, mounting, and performance issues are covered in the [storage troubleshooting section](/docs/on-demand/storage-and-ports#troubleshooting).
  </Accordion>
</AccordionGroup>

## Billing

Balance, deposits, and charge questions are covered in [Billing & Payments](/docs/general/billing-payments). The most common surprise: billing starts the moment an instance becomes ready and continues until termination — even when the GPU is idle.

## Still stuck?

Contact [support](/docs/general/support) — include your instance ID, region, timestamps, and the exact error output.