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

# Troubleshooting

> Common GPU instance issues and solutions.

export const RuncrateStyles = () => {
  if (typeof document !== 'undefined' && !document.getElementById('runcrate-overrides')) {
    const s = document.createElement('style');
    s.id = 'runcrate-overrides';
    s.textContent = `
      /* Match Runcrate's rounding scale (--radius: 0.75rem) */
      .rounded-sm { border-radius: 0.5rem !important; }   /* 8px */
      .rounded-md { border-radius: 0.625rem !important; } /* 10px */
      .rounded-lg { border-radius: 0.75rem !important; }  /* 12px */
      .rounded-l-sm { border-top-left-radius: 0.5rem !important; border-bottom-left-radius: 0.5rem !important; }
      .rounded-r-sm { border-top-right-radius: 0.5rem !important; border-bottom-right-radius: 0.5rem !important; }
      .rounded-l-md { border-top-left-radius: 0.625rem !important; border-bottom-left-radius: 0.625rem !important; }
      .rounded-r-md { border-top-right-radius: 0.625rem !important; border-bottom-right-radius: 0.625rem !important; }
      .rounded-l-lg { border-top-left-radius: 0.75rem !important; border-bottom-left-radius: 0.75rem !important; }
      .rounded-r-lg { border-top-right-radius: 0.75rem !important; border-bottom-right-radius: 0.75rem !important; }

      /* Cards: never pure white in light mode */
      .card { background-color: #fcfcfc !important; border-radius: 0.75rem !important; }
      html.dark .card { background-color: #141414 !important; }

      /* Docs hero box */
      .rc-hero { background-color: #fcfcfc; border: 1px solid #e0e0e0; }
      html.dark .rc-hero { background-color: #141414; border-color: #242424; }
      html.dark .rc-hero h1 { color: #f5f5f5; }

      /* Runcrate scrollbar — thin, transparent track, hide-until-hover thumb */
      ::-webkit-scrollbar { width: 6px; height: 6px; background-color: transparent; }
      ::-webkit-scrollbar-track { background-color: transparent; }
      ::-webkit-scrollbar-thumb { background-color: rgba(155, 155, 155, 0.5); border-radius: 10px; transition: opacity 0.3s ease; opacity: 0; }
      ::-webkit-scrollbar-thumb:hover { background-color: rgba(155, 155, 155, 0.7); }
      *:hover::-webkit-scrollbar-thumb,
      *:focus::-webkit-scrollbar-thumb,
      *:active::-webkit-scrollbar-thumb { opacity: 1; }
      * { scrollbar-width: thin; scrollbar-color: rgba(155, 155, 155, 0.5) transparent; }
    `;
    document.head.appendChild(s);
  }
  return null;
};

<RuncrateStyles />

Solutions for common issues when deploying, connecting to, and using GPU instances.

## Deployment Issues

<AccordionGroup>
  <Accordion title="Instance stuck in 'Creating' state">
    If your instance has been in the `creating` state for more than 5 minutes:

    1. **Wait a few more minutes.** Some GPU configurations take longer to provision, especially multi-GPU setups.
    2. **Try terminating and redeploying.** Terminate the stuck instance and create a new one.
    3. **Try a different region.** The GPU you selected may have limited availability in the chosen region.
    4. **Contact support** if the issue persists across multiple attempts.
  </Accordion>

  <Accordion title="Deployment fails immediately">
    If your instance goes to a failed state right after deploying:

    * **Insufficient credits.** Check your balance on the [Billing page](/billing/overview). You need enough credits for at least one hour of usage.
    * **Invalid configuration.** Ensure your CPU, memory, and disk settings are within the allowed ranges for the selected GPU.
    * **Try redeploying** with a different configuration or region.
  </Accordion>

  <Accordion title="No GPUs available">
    GPU availability fluctuates based on demand.

    * **Try a different region.** The same GPU may be available in another region.
    * **Try a different GPU type.** Similar-tier GPUs may have availability (e.g., A100 40GB instead of A100 80GB).
    * **Try again later.** GPUs free up as other users terminate their instances.
    * **Join our [Discord](https://discord.gg/8DJf4N42JU)** for availability updates.
  </Accordion>
</AccordionGroup>

## Connection Issues

<AccordionGroup>
  <Accordion title="SSH connection refused">
    ```
    ssh: connect to host 203.0.113.42 port 22: Connection refused
    ```

    * **Check the instance status.** It must be `deployed` to accept SSH connections.
    * **Verify the port.** Some instances use a non-standard SSH port. Check the instance detail page for the correct port.
    * **Wait for startup.** If the instance was just deployed, networking may need 1-2 minutes to initialize.
    * **Check the IP address.** Make sure you are using the IP shown on the instance detail page.
  </Accordion>

  <Accordion title="Permission denied (publickey)">
    ```
    Permission denied (publickey).
    ```

    * **Correct key?** Make sure you are specifying the private key that matches the public key you attached during deployment: `ssh -i ~/.ssh/your_key ...`
    * **Key permissions.** Your private key file must have restricted permissions:
      ```bash theme={"theme":"github-dark"}
      chmod 600 ~/.ssh/your_key
      ```
    * **Correct user.** Always connect as `root`: `ssh root@<ip> ...`
    * **Key not attached.** If you did not select this key during deployment, there is no way to add it after the fact. You will need to redeploy with the correct key.
  </Accordion>

  <Accordion title="Connection timed out">
    ```
    ssh: connect to host 203.0.113.42 port 22: Operation timed out
    ```

    * **Check your network.** Make sure you can reach the internet and that your firewall or VPN is not blocking outbound SSH.
    * **Verify IP and port.** Confirm the values on the instance detail page.
    * **Instance may be unhealthy.** If the instance was previously working, it may have encountered an issue. Try terminating and redeploying.
  </Accordion>
</AccordionGroup>

## GPU Issues

<AccordionGroup>
  <Accordion title="nvidia-smi not found">
    ```
    bash: nvidia-smi: command not found
    ```

    * This should not happen with the default OS images. If you see this:
      1. Check if the NVIDIA driver is loaded: `lsmod | grep nvidia`
      2. Try restarting the driver: `sudo nvidia-smi` or check the path: `which nvidia-smi`
      3. If using a custom image, you may need to install the NVIDIA driver manually.
      4. If the issue persists, terminate and redeploy with a standard template (Devbox or Finetune).
  </Accordion>

  <Accordion title="CUDA out of memory">
    ```
    RuntimeError: CUDA out of memory.
    ```

    * **Reduce batch size.** This is the most common fix.
    * **Use gradient checkpointing** to trade compute for memory.
    * **Use mixed precision** (`fp16` or `bf16`) to halve memory usage.
    * **Check for memory leaks.** Run `nvidia-smi` to see if another process is using GPU memory.
    * **Upgrade your GPU.** If you consistently run out of memory, deploy an instance with more VRAM (e.g., A100 80GB or H100).
  </Accordion>

  <Accordion title="PyTorch cannot see GPU">
    ```python theme={"theme":"github-dark"}
    >>> torch.cuda.is_available()
    False
    ```

    * **Check CUDA installation:** `nvcc --version`
    * **Check driver:** `nvidia-smi`
    * **PyTorch CUDA mismatch.** Your PyTorch version may be compiled for a different CUDA version. Reinstall with the correct version:
      ```bash theme={"theme":"github-dark"}
      pip install torch --index-url https://download.pytorch.org/whl/cu121
      ```
    * **Use the Finetune template.** It has PyTorch and CUDA pre-installed and compatible.
  </Accordion>
</AccordionGroup>

## Billing Issues

<AccordionGroup>
  <Accordion title="Instance terminated unexpectedly">
    Instances are automatically terminated when your credit balance reaches zero.

    * **Check your balance** on the [Billing page](/billing/overview).
    * **Enable auto-recharge** to automatically add credits when your balance drops below a threshold.
    * If you believe the termination was an error, contact support with your instance ID.
  </Accordion>

  <Accordion title="Still being charged after termination">
    Billing stops as soon as the instance reaches the `terminated` state.

    * **Check the timeline.** Charges are billed per hour. If you terminated mid-hour, you are billed for the full hour.
    * **Verify the instance is terminated.** Go to the Instances page and confirm the status shows `terminated`.
    * If your balance decreased after termination, check if you have other active instances.
    * Contact support if the charges do not match your usage.
  </Accordion>
</AccordionGroup>

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Discord Community" icon="brand-discord" href="https://discord.gg/8DJf4N42JU">
    Get help from the team and community in real time.
  </Card>

  <Card title="Email Support" icon="mail" href="mailto:support@runcrate.ai">
    Reach us at [support@runcrate.ai](mailto:support@runcrate.ai) for account and billing issues.
  </Card>
</CardGroup>