Troubleshooting

Common issues running the stack locally. Start everything with ./scripts/dev.sh (or ./scripts/dev.ps1 on Windows — every dev.sh --flag below has a dev.ps1 -Flag equivalent: --clean → -Clean, --seed-only → -SeedOnly, --infra-only → -InfraOnly) (see deployment.md).

Docker build fails on the Python agents (`agent-framework` resolution)

Symptom: a wall of agent-framework … cannot be used / agent-framework-azure-ai-search conflicts during uv sync. Cause: re-resolving the pre-release MAF graph against live PyPI. Fix is already in the Dockerfile — it syncs from the committed agents/python/uv.lock with uv sync --frozen. If you hit this, ensure uv.lock is present and run a clean build:

./scripts/dev.sh --clean        # nuke volumes + rebuild
# or
docker compose build --no-cache orchestrator

To refresh deps deliberately: cd agents/python && uv lock (commit the new lock).

Port already in use (5432 / 6379 / 8080 / 3000 / 18888)

Another stack (or a host Postgres/Redis) holds the port. Find and stop it:

lsof -nP -iTCP:5432 -sTCP:LISTEN     # who's listening
docker compose down                   # stop this stack

The compose services use 5432 (Postgres), 6379 (Redis), 8080 (orchestrator), 8081–8085 (specialists), 3000 (frontend), 18888 (Aspire).

Chat returns an error / “encountered an issue”

The LLM is never mocked. Set a real key in the repo .env:

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4.1

(or the AZURE_OPENAI_* vars for Azure). Restart the orchestrator + agents.

You’re hitting the wrong backend, or the orchestrator is pointed at a different DB. Confirm :8080 is the e-commerce orchestrator (curl localhost:8080/health → {"service":"orchestrator"}) and that the DB was seeded (./scripts/dev.sh --seed-only).

Product browse + chat are anonymous via optional_auth. If anonymous GET /api/products returns 401, the orchestrator image predates that change — rebuild it: docker compose up -d --build --no-deps orchestrator.

DB connection refused / empty data

Postgres not ready or not seeded. docker compose ps (db healthy?), then ./scripts/dev.sh --seed-only. The seeder is deterministic (random.seed(42)).

Embeddings missing (semantic search empty)

cd agents/python && uv run python -m scripts.generate_embeddings

UI changes not showing in the running stack

The frontend is a built container. Rebuild it: docker compose up -d --build --no-deps frontend (or run cd web && pnpm dev on a free port).

Aspire dashboard empty (no traces)

Open http://localhost:18888. Ensure OTEL_ENABLED is on and the OTLP endpoint points at the Aspire container. See telemetry.md.

Source: docs/troubleshooting.md — this page is generated from the repository.