# Troubleshooting

> Fix common instance problems, from SSH errors and unreachable ports to GPUs your code can't see.

This page lists common problems with instances, grouped by what you were doing, each with its cause and fix.

## Starting and stopping

### The instance takes a long time to start

The first start of an image downloads it, which takes a few minutes for a large image. Later starts of the same image are faster. Billing starts only when the container starts.

### The instance won't start again

Starting needs a free GPU of the same model and credit for one hour of the instance's rate. If GPUs of that model are busy, try again later, or deploy a new instance on another GPU model.

### The instance keeps restarting

Its main process exits. Open the **Logs** tab for the error. Common causes:

- **The start command uses shell features** such as `&&`, pipes or `$VARIABLES`. It runs without a shell; put the commands in a script and run the script.
- **The start command finishes.** An instance runs as long as its main process does. Start a long-running server, or leave the start command empty to keep the image's own.
- **The image isn't built for linux/amd64.** See [Check that your image will run](/templates/custom-images#check-that-your-image-will-run).

An instance that crashes 10 times in a row, each time within 10 minutes of starting, is stopped for you.

### The instance stopped on its own

Open its **Activity** tab to see why:

- **Credit ran out:** add credit on the [Billing page](https://console.cloud.featherless.ai/billing), then start the instance again.
- **It kept crashing:** see [The instance keeps restarting](#the-instance-keeps-restarting).

### My files or installed packages are gone after a stop or restart

They were on the container disk, which is erased when an instance stops or restarts, including the restart that applies an edit. Keep files on a network volume mounted at `/workspace`, and keep a `requirements.txt` on the volume so reinstalling packages is one command. See [Choose where to keep each file](/storage#choose-where-to-keep-each-file).

### I can't see an instance a teammate deployed

It's in another organization. Switch organizations from the menu at the top of the console's sidebar.

## Running code

### My code can't find the GPU

Your framework reports no GPU, for example `torch.cuda.is_available()` returns `False` in PyTorch. Either the instance runs on CPU compute, or the image is built for the other GPU vendor: ROCm images need AMD GPUs, and CUDA images need NVIDIA GPUs. Deploy again with a matching template and GPU.

### The GPU runs out of memory

Your framework reports that GPU memory is exhausted, for example `HIP out of memory` or `CUDA out of memory` in PyTorch. The model, its activations and the batch don't fit. Lower the batch size, load the model in a lower precision such as `bfloat16`, or deploy with more GPUs and split the model across them. The **Metrics** tab shows each GPU's memory over time.

### A program prints Killed

The instance ran out of memory, and the program using the most was stopped. Load less data at once, or deploy a larger size: each GPU comes with its own share of memory, and CPU sizes list theirs.

### Downloads or installs fail with No space left on device

The container disk or a network volume is full. See [Storage troubleshooting](/storage/troubleshooting#downloads-or-installs-fail-with-no-space-left-on-device).

### My secret isn't in the environment

Secret variables aren't environment variables. Each one is a file under `$FEATHERLESS_SECRETS_PATH`. Read it in your code, or export it for tools that expect an environment variable:

```bash
export HF_TOKEN="$(cat "$FEATHERLESS_SECRETS_PATH/HF_TOKEN")"
```

### A gated Hugging Face model won't download

Hugging Face needs your token for gated models. Add it as a secret variable named `HF_TOKEN` when you deploy, export it as shown in [My secret isn't in the environment](#my-secret-isnt-in-the-environment), and accept the model's license on its Hugging Face page.

### Models download again every time the instance starts

Hugging Face caches models on the container disk, which a stop erases. Set the environment variable `HF_HOME` to a folder on a network volume, such as `/workspace/hf`, so models download once.

### My program's output isn't in the logs

Logs show only the instance's main process. Output from programs you start in the terminal or over SSH stays in that terminal. See [Send your program's output to the logs](/instances/logs-and-metrics#send-your-programs-output-to-the-logs).

## Connecting

### SSH says Permission denied (publickey)

- **The key isn't added:** your organization's SSH keys are on the [Credentials page](https://console.cloud.featherless.ai/credentials/ssh-keys). Add the public key of the key you connect with.
- **Your SSH client offers a different key:** name it with `-i`, for example `ssh -i ~/.ssh/id_ed25519 <instance-id>@ssh.cloud.featherless.ai`.
- **The instance isn't running, or the ID is wrong:** copy the command from the instance's **Connect** tab.
- **The instance runs a custom image without SSH:** see [Check that your image will run](/templates/custom-images#check-that-your-image-will-run), or use the browser terminal.

### VS Code or Cursor can't connect

Remote-SSH connects to a host from your SSH config. Add an entry for the instance to `~/.ssh/config`, then connect to `my-instance`:

```text
Host my-instance
  HostName ssh.cloud.featherless.ai
  User <instance-id>
  IdentityFile ~/.ssh/id_ed25519
```

### A program stopped when I disconnected

It ran in a plain SSH session, which ends its programs when it closes. Start long-running work in tmux, from the browser terminal or with `featherless-cloud instance tmux my-instance`, and it keeps running after you disconnect. See [Keep programs running with tmux](/instances/connect#keep-programs-running-with-tmux).

### The browser terminal closed

It closes after 30 minutes without activity. Programs in its tmux session keep running; open the **Terminal** tab again to get back to them.

### My tmux sessions are gone

tmux sessions end when the instance stops or restarts. Restart the programs, or make the main one the instance's start command so it starts with the instance.

## Public ports

### A public port returns 503 with Connection refused

Nothing is accepting connections on that port inside the instance. Either no service is running, it listens only on `127.0.0.1`, or it stopped when the session that started it ended. Check from the instance's terminal:

```bash
curl -s -o /dev/null -w "%{http_code}\n" localhost:8000
```

If that prints `200` but the address still returns `503`, restart the service listening on `0.0.0.0`.

### My web app only listens on localhost

Many servers listen on `127.0.0.1` unless you tell them otherwise, which makes the public address return `503`. Start them on all interfaces:

<table>
<thead>
  <tr>
    <th>
      Server
    </th>
    
    <th>
      Listen on all interfaces
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Uvicorn (FastAPI)
    </td>
    
    <td>
      <code>
        uvicorn app:app --host 0.0.0.0 --port 8000
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Flask
    </td>
    
    <td>
      <code>
        flask run --host 0.0.0.0 --port 8000
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Gradio
    </td>
    
    <td>
      <code>
        demo.launch(server_name="0.0.0.0", server_port=8000)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      JupyterLab
    </td>
    
    <td>
      <code>
        jupyter lab --ip 0.0.0.0 --port 8888
      </code>
    </td>
  </tr>
</tbody>
</table>

### A connection to a public port drops after 5 minutes

A connection with no traffic for 300 seconds is closed. Send keepalive messages, such as WebSocket pings, more often than that.

### A vLLM server returns 401

vLLM started with an API key rejects requests without it. Send the key as a bearer token: `-H "Authorization: Bearer $VLLM_API_KEY"`. See [Serve an LLM with vLLM](/examples/vllm-server).

### A model server's address doesn't answer yet

The server is still downloading or loading the model, which takes minutes for large models. Follow its progress on the **Logs** tab; vLLM prints `Application startup complete.` when it's ready.

## Getting help

If you're still stuck, ask us on [Discord](https://discord.com/invite/7gybCMPjVA). Include:

- the instance ID, from the instance's page or `featherless-cloud instance get <name>`;
- what you did, and the exact error from the **Logs** or **Activity** tab;
- when it happened.
