Troubleshooting¶

Start with devbox doctor — it checks most prerequisites automatically:

devbox doctor --server dev1

Common Issues¶

Cause: No devbox.yaml in the current directory.

Fix:

devbox init

Or specify the project directory:

devbox up ./path/to/project

Cause: devbox.yaml is missing the name or server field.

Fix: Add the missing field to your devbox.yaml:

name: my-project
server: dev1

See Configuration Reference for all required fields.

Cause: SSH is not configured for the server name, or the server is unreachable.

Fix:

If it fails, add an entry to ~/.ssh/config:

Host dev1
    HostName 100.x.x.x
    User your-username

Cause: Docker is not installed or the daemon is not running on the server.

Fix:

Install Docker on the server:

ssh dev1 "curl -fsSL https://get.docker.com | sh"

Start the Docker daemon:
```
ssh dev1 "sudo systemctl start docker"
```
Add your user to the docker group (avoids needing sudo):
```
ssh dev1 "sudo usermod -aG docker $USER"
```

Cause: Tailscale is not running, not logged in, or doesn't have permissions to serve ports.

Fix:

Check Tailscale status on the server:
```
ssh dev1 "tailscale status"
```
If not connected, log in:
```
ssh dev1 "sudo tailscale up"
```
Verify that Tailscale Funnel/Serve is enabled in your Tailscale admin console under DNS settings.

Cause: Another container or process is using the same port on the server.

Fix:

Check what's using the port:
```
ssh dev1 "sudo lsof -i :8080"
```
Either stop the conflicting process or change the port in devbox.yaml:
```
ports:
  app: 8081  # Use a different port
```

Cause: A workspace with the same name already exists on the server.

What happens: devbox up automatically starts the existing workspace instead of creating a new one. This is expected behavior.

To start fresh:

devbox destroy my-project
devbox up

Cause: The git repository is large and takes time to clone over SSH.

Fix:

Use a shallow clone by keeping your repo lean
Ensure the server has good network connectivity
If the repo is already cloned, devbox up will reuse it (only the first run is slow)

Cause: Your user doesn't have permission to run Docker commands or access the workspace directory.

Fix:

Add your user to the docker group:

ssh dev1 "sudo usermod -aG docker $USER"

Log out and back in for the group change to take effect:
```
ssh dev1  # reconnect
```

If your issue isn't listed here: