Skip to content
AI Academy

Troubleshoot a problem

Start with the symptom below. Run WSL commands in the environment hosting the backend. Collect evidence before restarting or deleting anything.

Cannot connect to port 8000

Section titled “Cannot connect to port 8000”

Check whether your terminal process is running or inspect systemctl status devsecops-ai. Confirm the configured port and bind address. A working Windows SSH connection does not establish backend access inside WSL.

403: missing or invalid API key

Section titled “403: missing or invalid API key”

Use Authorization: Bearer with the configured key. Confirm you are contacting the intended backend. Do not print .env into a log or issue. See first query for hidden terminal input.

422: request validation failed

Section titled “422: request validation failed”

Check the response’s validation detail. /api/v1/query takes JSON; /api/v1/router/test takes URL query parameters. The committed API limits query to 20,000 characters. A locally modified installation may differ; inspect its OpenAPI schema.

429: request limit exceeded

Section titled “429: request limit exceeded”

Wait for the one-minute window. Query and ingest requests share one in-memory history per token, with different thresholds. Changing RATE_LIMIT_* in .env does not change the current implementation.

Empty answer or slow generation

Section titled “Empty answer or slow generation”

Inspect Ollama logs and installed models. Check memory, selected model, and context length. The backend sends OLLAMA_THINK=false by default; behavior depends on the actual model/runtime. Do not generalize one host’s timings to every deployment.

Import error or missing log directory

Section titled “Import error or missing log directory”

Check the working directory and import path. Follow the explicit startup command in installation. Create logs before importing the application. The automated deployment configurations have known path mismatches.

ChromaDB schema error

Section titled “ChromaDB schema error”

For errors such as no such column: collections.topic, stop mixing Python environments. The backend pins ChromaDB 0.4.22. Preserve the store and recover with a compatible environment or verified backup; do not blindly delete or recreate it.

Unexpected sources or old conversation context

Section titled “Unexpected sources or old conversation context”

Check the memory limitations and retrieval behavior. Semantic history is not isolated by thread; limited message reads return older messages first. A new thread alone does not fix this.

Section titled “Site link or search result is missing”

Check whether you are viewing the intended GitLab Pages deployment. Old routes should redirect to current pages. Report the source URL, destination, and documentation revision. Search is generated at build time and should be checked against the built site.

Still stuck? Report the sanitized error, source revision, model names, and deployment method in GitLab Issues. Never attach credentials, full environment files, or raw conversation stores.