Skip to content

Common Local Issues

Most local problems fall into one of four categories: a missing process, missing dependencies, uninitialized submodule, or stale local state. This page covers the most common ones.

The API won't start

Symptom: uvicorn fails with an import error or crashes immediately.

First, make sure your virtual environment is active and dependencies are installed:

source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --reload-dir app

If the error mentions v16 or No module named 'v16', the git submodule hasn't been initialized:

git submodule update --init --recursive

If the error mentions a missing Python package, run pip install -r requirements.txt again.

The frontend can't reach the API

Symptom: The dashboard loads at http://localhost:5173 but API calls fail with a network error or 502.

The Vite proxy expects the backend on port 8000. Confirm:

  1. The API is running: curl http://localhost:8000/v1/healthz
  2. The frontend dev server is running: open http://localhost:5173
  3. Both are running at the same time

If the API is on a different port, update frontend/vite.config.ts to match.

Login fails

Symptom: The login form returns an error, or curl gets a 401.

For local dev, use the built-in debug credentials:

curl -s http://localhost:8000/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"debug@example.com","password":"vega-debug-password"}'

If this fails:

  • Confirm VEGA_AUTH_PROVIDER is not set to cognito (or if it is, you need valid Cognito configuration).
  • Confirm the API started without errors.
  • Check the API terminal for any auth-related error messages.

Scans stay in queued status

Symptom: You create a scan from the dashboard, but it stays queued and never runs.

This happens when the scan execution mode requires an external process to pick up the scan, but that process isn't running.

  • If VEGA_SCAN_EXECUTION_MODE=external, start the worker:

    python scripts/run-scan-worker.py

  • If VEGA_SCAN_EXECUTION_MODE=sqs, you also need VEGA_SCAN_QUEUE_URL set to a valid SQS URL and AWS credentials configured.

  • If VEGA_SCAN_EXECUTION_MODE=thread (the default), the scan should run immediately. If it doesn't, check the API logs for errors.

Codex / Docker scan failures

Symptom: Scans start but fail quickly with a Codex-related error.

The default scan setup runs Codex inside a Docker container. Two things are needed:

  1. Docker must be running on your machine.

  2. The Codex runner image must be built:

    scripts/build-codex-runner-image.sh

If you don't want to use Docker during development, you can bypass the container by setting VEGA_V16_CODEX_BIN to a locally installed codex binary:

VEGA_V16_CODEX_BIN=codex uvicorn app.main:app --reload --reload-dir app

Local state looks corrupted or out of date

Symptom: Projects, scans, or findings show unexpected data, or the API returns errors about missing records.

Local state lives in data/. You can inspect it directly (it's JSON) or delete specific subdirectories to reset parts of the state. To start completely fresh:

rm -rf data/

The backend will recreate the directory structure on next startup.

Don't delete data/ if you have test results you need

If you've run real scans and need the findings for review, back up data/ before deleting it.

Port already in use

Symptom: uvicorn or npm run dev fails with address already in use.

Find and kill the process using the port:

# Find what's using port 8000
lsof -i :8000

# Kill it
kill <PID>

Or start on a different port:

uvicorn app.main:app --reload --reload-dir app --port 8001

If you change the backend port, update the Vite proxy config in frontend/vite.config.ts to match.