Common Issues

Quick-reference solutions for common issues. For detailed troubleshooting guides, see the Troubleshooting Overview.

CLI Issues

SSH Connection Fails

Symptom: ssh: connect to host ... port 22: Connection refused

Solutions:

1. Verify the instance is running with brev list
2. If you recently restarted the instance, run brev refresh to update SSH config with the new IP
3. Check your network allows outbound SSH (port 22)

$
# Check instance status
$
brev list
$
$
# Update SSH config
$
brev refresh
$
$
# Try connecting again
$
brev shell my-instance

Instance not appearing in CLI

Instances created in the web console need to be synced to your local CLI.

$
brev refresh

Login Fails

Symptom: Browser authentication doesn’t complete

Solutions:

1. Try brev login --skip-browser and manually open the URL
2. For headless environments, use brev login --token
3. Clear browser cookies for brev.nvidia.com

$
# Skip auto-opening browser
$
brev login --skip-browser
$
$
# Token-based login for headless/CI
$
brev login --token

Authentication expired

If commands fail with auth errors, re-authenticate with the CLI.

$
brev logout && brev login

Editor Won’t Open

Symptom: brev open fails with “command not found”

Solutions:

1. Verify the editor is installed and in your PATH
2. For VS Code: ensure code command is available (install from Command Palette: “Shell Command: Install ‘code’ command in PATH”)
3. For Cursor/Windsurf: check application settings for CLI installation

$
# Set a different default editor
$
brev open --set-default cursor

Reset Brev CLI

If instances are missing or the CLI is behaving unexpectedly, force a refresh:

$
brev refresh

This updates the SSH config and ensures the daemon is running.

Connectivity Issues

SSH connection refused after restart

Instance IP addresses may change after a restart. Run refresh to update your SSH config.

$
# Update SSH config with new IPs
$
brev refresh
$
$
# Then try connecting again
$
brev shell my-instance

Port forward not working

Symptom: localhost:port returns “connection refused”

Solutions:

1. Verify the service is running on the instance: brev shell my-instance then check the port
2. Check the port mapping is correct (local:remote)
3. Ensure no local service is using the same port

$
# On the instance, check if service is listening
$
netstat -tlnp | grep 8888
$
$
# Forward with explicit port mapping
$
brev port-forward my-instance --port 8888:8888
$
$
# If local port is in use, map to different local port
$
brev port-forward my-instance --port 9999:8888

Container and Docker Compose Issues

Debugging container build failures

If your container or Docker Compose build is failing, check the logs:

$
# SSH into the host machine
$
brev shell my-instance --host
$
$
# Navigate to workspace and view logs
$
cd workspace
$
docker compose logs

JupyterLab tunnel issues

If you can’t access JupyterLab and verified your container is running correctly, check the Cloudflare tunnel:

$
# SSH into the host
$
brev shell my-instance --host
$
$
# Check if cloudflared is running
$
ps aux | grep cloudflared
$
$
# Check service status
$
sudo systemctl status cloudflared
$
$
# If not running, start it
$
sudo systemctl start cloudflared

Docker socket permission denied

If you get “permission denied while trying to connect to the Docker daemon socket”:

$
sudo chmod 666 /var/run/docker.sock

Then re-run your Docker command.

Viewing startup logs

If something went wrong during instance setup (e.g., empty project folder, failed git clone), check the startup logs:

$
brev shell my-instance --host
$
sudo cat /var/log/brev-workspace.log

This shows the full initialization sequence, including SSH key setup and repository cloning.

GPU Issues

GPU not available in container

Ensure you’re using the --gpus all flag when running Docker containers.

$
# Run with GPU access
$
docker run --gpus all -it your-image
$
$
# Verify GPU in container
$
nvidia-smi

Verifying GPU setup

After launching an instance, verify the GPU is properly configured:

$
# Check NVIDIA driver and GPU visibility
$
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

CUDA out of memory

Your model or batch size is too large for the GPU VRAM.

• Reduce batch size
• Use gradient checkpointing
• Use mixed precision (fp16/bf16)
• Upgrade to a GPU with more VRAM

Instance Issues