***

title: Common Issues
description: >-
Quick-reference solutions for frequently encountered NVIDIA Brev CLI,
connectivity, container, and GPU issues.
----------------------------------------

Quick-reference solutions for common issues. For detailed troubleshooting guides, see the [Troubleshooting Overview](/troubleshooting).

## 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)

```bash
# Check instance status
brev list

# Update SSH config
brev refresh

# Try connecting again
brev shell my-instance
```

<Callout intent="info">
  For persistent SSH authentication issues on macOS, see [CLI SSH Authentication (macOS)](/troubleshooting/cli-ssh-authentication).
</Callout>

### Instance not appearing in CLI

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

```bash
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

```bash
# 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.

```bash
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

```bash
# Set a different default editor
brev open --set-default cursor
```

<Callout intent="info">
  For VS Code connection issues on Windows/WSL, see [VS Code Connection (Windows/WSL)](/troubleshooting/ide-connectivity/vscode-windows-wsl).
</Callout>

### Reset Brev CLI

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

```bash
brev refresh
```

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

<Callout intent="info">
  For Linux CLI installation issues, see [CLI Installation (Linux)](/troubleshooting/cli-installation/cli-installation-linux).
</Callout>

## Connectivity Issues

### SSH connection refused after restart

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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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
```

<Callout intent="info">
  If your container or Docker Compose is setting up its own JupyterLab server, ensure it doesn't conflict with the host JupyterLab tunnel.
</Callout>

### Docker socket permission denied

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

```bash
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:

```bash
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.

```bash
# 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:

```bash
# 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

<Callout intent="info">
  For GPU detection issues with PyTorch and Unsloth on H100 instances, see [GPU Detection and PyTorch Setup](/troubleshooting/instances-gpus/gpu-detection-pytorch).
</Callout>

## Instance Issues

<Callout intent="info">
  For instances stuck in "Waiting" state, see [Instance Stuck in Waiting State](/troubleshooting/instances-gpus/instance-waiting-state).
</Callout>