Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/geremyjampiersalasgarcia-eng/Caso_Practico_Semillero_IA/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues encountered when running Mesa de Ayuda IA locally. The system has several moving parts — Docker containers, a Python virtual environment, ChromaDB on disk, and a Next.js frontend — that must start in the correct order and be configured consistently. Most errors fall into one of the categories below.
Symptom: The backend fails to start with a message such as could not connect to server or connection refused on port 5433.Cause: The Docker PostgreSQL container has been started but has not yet finished initializing. Docker reports the container as “running” before the database process inside it is ready to accept connections.Solution:
  1. Start only the infrastructure containers first, and wait for them to reach the healthy state: 
    docker-compose up -d postgres phoenix
  2. Confirm the postgres container is healthy before proceeding: 
    docker-compose ps
    The STATUS column should show healthy, not just running. The healthcheck runs pg_isready every 5 seconds with up to 5 retries, so allow 10–30 seconds after docker-compose up.
  3. Only then start the backend: 
    cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
The docker-compose.yml configures a healthcheck on the postgres service using pg_isready -U mesa_ayuda_user -d mesa_ayuda_db. If you see repeated restarts, check Docker Desktop logs for the mesa_ayuda_db container for initialization errors.
Symptom: Agent responses fail with an error like 429 Resource has been exhausted or RESOURCE_EXHAUSTED: Quota exceeded for quota metric.Cause: The Google AI Studio free tier is limited to 15 requests per minute (RPM). Mesa de Ayuda IA uses LangGraph, which fires multiple sequential Gemini API calls for a single chat message:
  • 1 call for the classifier node (intent detection)
  • 1 call per agent node invoked (up to 3 for mixed-intent queries)
  • 1 call for the consolidator node (if multiple agents ran)
A single complex message can therefore consume 5 Gemini API calls, hitting the free-tier limit quickly.Solution:
  • For local testing: Wait 10–15 seconds between chat messages. This gives the RPM counter time to reset before the next multi-call chain.
  • For production: Upgrade to a paid Gemini API tier, which offers significantly higher RPM quotas and removes the 15 RPM cap.
  • For load testing: Use scripts/test_production.py with a time.sleep() between calls to simulate realistic pacing without triggering rate limits.
Symptom: The backend starts but all chat requests fail with an error such as 404 models/gemini-1.5-flash is no longer available or This model version has been deprecated.Cause: The LLM_MODEL_NAME in your .env (or its default in app/config.py) points to a deprecated Gemini model name. Google periodically retires specific model versions and replaces them with newer ones or stable aliases.Solution:Open backend/.env and set the model to the latest stable alias:
LLM_MODEL_NAME=gemini-flash-lite-latest
Using the -latest suffix ensures the backend always resolves to the most recent non-deprecated version of that model family without requiring a manual .env update every time Google releases a new version.Restart the backend after saving .env:
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Symptom: Chat requests fail with Collection col_catalogo not found (or col_politicas / col_proceso_ventas). The backend starts without errors, but the first message returns an exception.Cause: The ChromaDB vector collections have not been populated. The data/chroma_db/ directory is either empty or does not exist because scripts/ingest.py was never run.Solution:Run the ingestion script from the backend/ directory with the virtual environment activated and GOOGLE_API_KEY set in .env:
cd backend
source venv/bin/activate   # Linux / macOS
# .\venv\Scripts\activate  # Windows

python scripts/ingest.py
The script will:
  1. Load the three knowledge-base documents from data/raw/
  2. Split them into chunks using RecursiveCharacterTextSplitter
  3. Generate embeddings with GoogleGenerativeAIEmbeddings (models/gemini-embedding-001)
  4. Persist three separate collections to data/chroma_db/: col_catalogo, col_politicas, and col_proceso_ventas
Re-indexing is safe to run multiple times — the script clears each collection before re-populating it.
Symptom: The Next.js UI loads at http://localhost:3000 but chat messages fail with network errors, CORS errors in the browser console, or the frontend shows “could not reach the server”.Cause: Either the backend is not running on port 8000, or the CORS middleware is not configured to allow requests from http://localhost:3000.Solution:
  1. Confirm the backend is running: 
    curl http://localhost:8000/api/v1/health
    You should receive a 200 OK response. If not, start the backend first.
  2. Check that CORS is configured correctly. In app/main.py, the allowed origins are hardcoded to http://localhost:3000: 
    app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
    If you are serving the frontend from a different port or domain, update allow_origins accordingly or add a CORS_ORIGINS env var and wire it into the middleware configuration.
  3. When running via docker-compose, the frontend container uses NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1. Ensure this variable is set correctly in docker-compose.yml or the frontend’s .env.local.
Symptom: The backend logs a warning like Falling back to SQLite at startup, or conversation history is lost after restarting the backend. The PostgreSQL audit_logs table appears empty when queried directly.Cause: The backend includes a fallback mechanism that switches to a local SQLite database if the PostgreSQL container is not reachable or if DATABASE_URL is misconfigured. This is intentional for resilience, but it means audit records and conversation history are written to a local file rather than PostgreSQL.Solution:
  1. Start the PostgreSQL container: 
    docker-compose up -d postgres
  2. Verify the DATABASE_URL in backend/.env matches the credentials in docker-compose.yml: 
    DATABASE_URL=postgresql://mesa_ayuda_user:mesa_ayuda_pass_2024@localhost:5433/mesa_ayuda_db
    Note the non-standard port 5433 — the container maps 5433 on the host to 5432 inside Docker.
  3. Restart the backend. On a successful connection you should see a structlog line confirming that SQLAlchemy created the tables in PostgreSQL.
Data written to SQLite while the fallback was active is not automatically migrated to PostgreSQL when the container comes back up. If conversation history from the fallback period is important, back up the SQLite file before restarting.
Symptom: The backend starts cleanly and accepts requests, but every chat response fails with a ChromaDB path error or no such file or directory for data/chroma_db/.Cause: The CHROMA_PERSIST_DIR setting defaults to the relative path data/chroma_db/. This path is resolved relative to whichever directory uvicorn was launched from. If you start uvicorn from the repository root instead of from backend/, Python resolves the path as ./data/chroma_db/ relative to the root, which does not exist.Solution:Always start uvicorn from inside the backend/ directory:
cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Alternatively, set CHROMA_PERSIST_DIR to an absolute path in backend/.env:
CHROMA_PERSIST_DIR=/absolute/path/to/Caso_Practico_Semillero_IA/backend/data/chroma_db
After correcting the working directory or path, run python scripts/ingest.py from within backend/ to ensure the collections are written to the correct location.

​
Getting Help

If you encounter an issue not covered above, please open a GitHub issue in the project repository. Include:
  • The exact error message and stack trace from the backend terminal
  • The output of docker-compose ps (to confirm container health states)
  • The relevant section of your backend/.env (with GOOGLE_API_KEY redacted)
  • The steps you followed before the error occurred
This information allows the maintainer to reproduce and fix the issue quickly.

Build docs developers (and LLMs) love

Get started for freeTalk to us