# Troubleshooting

## No-Podman / local dev

- **`make setup` fails to resolve deps** — make sure you're on Python 3.11 or
  3.12 (`python3 --version`); older interpreters aren't supported
  (`requires-python = ">=3.11"`).
- **`auralynq: command not found` after `make setup`** — activate the venv:
  `source .venv/bin/activate`.
- **Answers look extractive / low quality** — you're on the offline fallback
  (hash embeddings + in-memory store + extractive LLM). This is expected with
  no keys/extras installed and verifies pipeline *integrity*, not quality —
  see the Limitations section in `README.md`. Install `auralynq[embeddings]`
  and/or set an LLM provider key for real quality.
- **Web UI can't reach the API** — confirm `NEXT_PUBLIC_API_BASE` matches
  where `uvicorn` is actually listening (`http://localhost:8000/api` for the
  no-Podman dev flow), and that both processes are running.
- **Port already in use** — pass `--port` to `uvicorn`/`npm run dev` or stop
  whatever else is bound to 8000/3000.

## Podman stack

- **`make runtime-check` can't find a Compose command** — install
  `podman compose` (Podman v4+) or `podman-compose` separately; Auralynq
  resolves whichever is present via `scripts/check_container_runtime.sh`.
- **Cert warning in the browser** — expected with the baked-in self-signed
  cert; click *Advanced → Proceed*, or follow [server.md](server.md) to bind a
  real domain with Let's Encrypt.
- **502 right after `make stack-up`** — the web container is still booting;
  retry in a few seconds.
- **No answer in chat after a code change** — rebuild the image
  (`podman build --no-cache`, not `podman-compose build`, which can reuse
  stale layers) and fully cycle the stack (`podman-compose down` then
  `make stack-up`); hard-refresh the browser.
- **Rootless networking / container DNS issues** — `make stack-up`
  auto-patches the CNI conflist (CNI 0.4.0 + dnsname) on hosts where rootless
  Podman lacks container DNS; no sudo needed. On a netavark host this is a
  no-op.
- **Can't reach the stack from another machine** — open inbound TCP on
  whatever `AURALYNQ_HTTPS_PORT` is set to (default `8443`) in the firewall;
  every other port binds to loopback intentionally.

## Both modes

- **Secrets never show up** — they live only in `.env` (git-ignored); if a
  provider isn't detected, check the exact env var name against
  `.env.example` (nested settings use `__`, e.g. `AURALYNQ_LLM__PROVIDER`).
- **Corpus looks stale after deleting files by hand** — don't delete `data/`
  subfolders directly; use the API's guarded clear flow
  (`POST /corpus/clear/preview` then `/corpus/clear/confirm`) so the vector
  store, graph, and page cache are cleared together. See
  [no-podman.md](no-podman.md#clearing-your-data-safely).
- **Visual grounding shows "unavailable" for a document** — it was indexed
  before visual grounding metadata existed, or page rendering failed at
  ingest. Re-ingest the document, or use
  `POST /documents/{id}/render-pages` to re-render pages without a full
  reindex.

## Still stuck?

Open an issue with: your OS, Python/Node versions, which mode (no-Podman /
Podman / server), the exact command that failed, and the full error output.