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

# Troubleshooting

> Solutions for common issues when setting up and running OneGlanse.

***

## Camoufox fails to start

**Symptom:** Agent crashes immediately with a Python or pip error.

**Cause:** Python 3 is not on the PATH or the wrong binary is being used.

**Fix:** Find your Python 3 binary and set it explicitly:

```bash theme={null}
which python3
# e.g. /opt/homebrew/bin/python3
```

Add to `.env`:

```bash theme={null}
CAMOUFOX_PYTHON_BIN=/opt/homebrew/bin/python3
```

Then restart with `pnpm local`.

***

## Redis connection refused

**Symptom:** App or agent logs show `ECONNREFUSED 127.0.0.1:6379`.

**Cause:** The Redis Docker container is not running.

**Fix:** Check that Docker is running and the containers are up:

```bash theme={null}
docker ps
```

If the containers aren't listed, restart with `pnpm local`. If Docker itself isn't running, start it first.

***

## ClickHouse unavailable on first run

**Symptom:** Dashboard shows no data, or logs show a ClickHouse connection error shortly after startup.

**Cause:** ClickHouse takes 10–20 seconds to fully initialize on first boot.

**Fix:** Wait a moment and reload the page. If it persists, check the container:

```bash theme={null}
docker logs clickhouse_db
```

***

## Provider auth not saving

**Symptom:** A provider still shows as disconnected after you finish the local auth flow.

**Cause:** The Camoufox window was closed before the session was fully written.

**Fix:** Open the provider connection again, complete the full sign-in flow (including any 2FA or confirmation steps), and wait for the checkmark to appear in the OneGlanse UI before closing the browser window.

***

## Google sign-in is unavailable

**Symptom:** No Google sign-in button appears on the login page.

**Cause:** `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are not set in `.env`.

**Fix:** Add them to `.env`:

```bash theme={null}
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
```

Note: these control sign-in to the OneGlanse web app itself. They are separate from the Google / Gemini / AI Overview provider connections used for monitoring.

***

## Agent not processing prompts

**Symptom:** Prompts are queued but no responses appear.

**Causes and fixes:**

1. **Worker not started** — `pnpm local` starts both web and agent. If you started the web app separately, also run `pnpm dev:agent`.
2. **Provider auth missing** — run `pnpm auth` locally and confirm at least one provider completes sign-in. If a provider is still disconnected, rerun the auth flow for that provider.
3. **Redis not reachable** — see the Redis section above.

***

## Self-host: image pull fails

**Symptom:** `node scripts/run-compose.mjs bootstrap` fails with a Docker pull error, `unauthorized`, or an architecture mismatch such as `no matching manifest`.

**Cause:** Either the GHCR images are unavailable, you're not authenticated with GHCR, or the published image has not been published for your current CPU architecture yet.

**Fix:** Check outbound access to GHCR and Docker Hub, then retry:

```bash theme={null}
node scripts/run-compose.mjs bootstrap
```

If the only problem is an architecture mismatch, bootstrap now automatically falls back to a local Docker build on that machine. If you're maintaining a fork or explicitly want a source build, you can still run `pnpm self-host:build` directly.

***

## Migrations fail on startup

**Symptom:** The `migrate` container exits with an error; the web app won't start.

**Cause:** Postgres wasn't ready when migrations ran, or there's a schema conflict.

**Fix:**

```bash theme={null}
# Check migration logs
docker logs oneglanse-migrate

# Re-run migrations manually
pnpm db:migrate
```

If there's a schema conflict from a previous installation, check the Drizzle migration files in `packages/db/drizzle/`.

***

## VPS: sessions not transferring

**Symptom:** `pnpm upload:vps` runs but providers still show as disconnected on the VPS.

**Fixes:**

1. Confirm the VPS agent is running: `curl http://YOUR_VPS_IP:3333/health`
2. Confirm port `3333/tcp` is allowed by your VPS firewall or cloud security group
3. Check `ONEGLANSE_VPS_IP` and `AGENT_AUTH_UPLOAD_TOKEN` match your VPS `.env`
4. If `pnpm upload:vps` returns `401 Unauthorized`, the upload token on your local machine does not match the VPS `AGENT_AUTH_UPLOAD_TOKEN`
5. Check agent logs on the VPS: `docker logs oneglanse-agent-worker`