This page lists common problems with instances, grouped by what you were doing, each with its cause and fix.
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.
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.
Its main process exits. Open the Logs tab for the error. Common causes:
&&, pipes or $VARIABLES. It runs without a shell; put the commands in a script and run the script.linux/amd64. See 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.
Open its Activity tab to see why:
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.
It's in another organization. Switch organizations from the menu at the top of the console's sidebar.
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.
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.
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.
The container disk or a network volume is full. See Storage troubleshooting.
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:
export HF_TOKEN="$(cat "$FEATHERLESS_SECRETS_PATH/HF_TOKEN")"
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, and accept the model's license on its Hugging Face page.
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.
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.
-i, for example ssh -i ~/.ssh/id_ed25519 <instance-id>@ssh.cloud.featherless.ai.Remote-SSH connects to a host from your SSH config. Add an entry for the instance to ~/.ssh/config, then connect to my-instance:
Host my-instance
HostName ssh.cloud.featherless.ai
User <instance-id>
IdentityFile ~/.ssh/id_ed25519
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.
It closes after 30 minutes without activity. Programs in its tmux session keep running; open the Terminal tab again to get back to them.
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.
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:
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.
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:
| Server | Listen on all interfaces |
|---|---|
| Uvicorn (FastAPI) | uvicorn app:app --host 0.0.0.0 --port 8000 |
| Flask | flask run --host 0.0.0.0 --port 8000 |
| Gradio | demo.launch(server_name="0.0.0.0", server_port=8000) |
| JupyterLab | jupyter lab --ip 0.0.0.0 --port 8888 |
A connection with no traffic for 300 seconds is closed. Send keepalive messages, such as WebSocket pings, more often than that.
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.
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.
If you're still stuck, ask us on Discord. Include:
featherless-cloud instance get <name>;