> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safaridesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common problems when running SafariDesk with Docker Compose

# Troubleshooting

If something goes wrong during startup or operations, use the checks and fixes below to quickly isolate the problem.

Unless noted otherwise, Docker commands below work in Linux/macOS shells and Windows PowerShell.

## 1) Container fails to start

Check recent logs for the failing service:

These commands are the same in Linux/macOS and Windows PowerShell.

```bash theme={null}
docker compose logs --tail 200 api
docker compose logs --tail 200 worker
docker compose logs --tail 200 frontend
```

Common causes and fixes:

* Database not ready: wait a minute and retry `docker compose exec api python manage.py migrate`
* Missing env vars: open `Core/.env` and confirm required keys are present
* Wrong working directory: ensure you run compose commands from `Core/`

## 2) Database & migrations

If migrations fail or partially applied, try:

This command is the same in Linux/macOS and Windows PowerShell.

```bash theme={null}
docker compose exec api python manage.py migrate --fake-initial
```

If pgvector extension is missing, install it inside the API container:

This command is the same in Linux/macOS and Windows PowerShell.

```bash theme={null}
docker compose exec api python manage.py install_pgvector
```

## 3) Authentication / Admin user

If you cannot sign in with the superuser:

* Confirm `SUPERUSER_USERNAME`, `SUPERUSER_PASSWORD`, `SUPERUSER_EMAIL` in `.env`
* Check API logs: `docker compose logs api` to see account creation messages

## 4) WebSockets & real-time notifications

If notifications or WebSocket features do not work:

* Confirm API is running and reachable from the frontend
* Check `VITE_API_URL` and WebSocket URL settings in `.env`
* For local testing, WebSocket URL often looks like `ws://localhost:9100/ws/notifications/`

## 5) When all else fails

* Restart the stack:

These commands are the same in Linux/macOS and Windows PowerShell.

```bash theme={null}
docker compose down
docker compose up -d --build
```

* Inspect container state: `docker compose ps` and `docker compose top`
* Search logs for stack traces and post the error if you need help

If you want, copy a short excerpt of the relevant logs and I can help interpret them.