Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/EllisYuan/ChatAgents/llms.txt

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

Most ChatAgents failures fall into one of five categories: container networking problems (the frontend cannot reach the backend), Nginx misconfiguration (wrong proxy_pass or missing WebSocket upgrade headers), API key or quota issues, session data loss from a missing volume mount, and performance bottlenecks from using a large model or too many crawl pages. Start by checking the log commands at the bottom of this page to identify which layer is producing errors, then jump to the relevant accordion below.

​
Docker issues

Symptom: The Streamlit UI renders but displays a banner indicating the backend is not reachable. Chat input is disabled.Common causes:
  • BACKEND_URL is set to http://localhost:8080 instead of the Docker service name
  • The chatbot-backend container is not running or has not yet passed its health check
  • Both containers are not on the same Docker network
Diagnosis:
# 1. Confirm both containers are running and backend is healthy
docker ps | grep chatbot
# Look for: chatbot-backend ... (healthy)

# 2. Check the BACKEND_URL environment variable inside the frontend container
docker exec chatbot-frontend env | grep BACKEND_URL
# Expected: BACKEND_URL=http://backend:8080

# 3. Test container-to-container connectivity directly
docker exec chatbot-frontend curl -s http://backend:8080/health
# Expected: {"message":"后端 API 正在运行","status":"healthy"}
Fix:In docker-compose.yml, verify:
  • BACKEND_URL uses the service name backend, not localhost or 127.0.0.1
  • Both backend and frontend services are in the same chatbot-network
  • The backend service has a healthcheck and frontend has depends_on: backend: condition: service_healthy
frontend:
  environment:
    - BACKEND_URL=http://backend:8080   # service name, not localhost
  depends_on:
    backend:
      condition: service_healthy
  networks:
    - chatbot-network
Recovery:
docker-compose down
docker-compose up -d --build
Symptom: Accessing https://your-domain.com/api/sessions (or any /api/ path) returns 404 Not Found from Nginx, even though curl http://localhost:8080/api/sessions works directly.Cause: A trailing slash on proxy_pass tells Nginx to strip the matched prefix (/api/) before forwarding. FastAPI never sees /api/sessions — it receives /sessions, which does not exist.Wrong config:
location /api/ {
    proxy_pass http://127.0.0.1:8080/;  # trailing slash strips /api/ prefix
}
Correct config:
location /api/ {
    proxy_pass http://127.0.0.1:8080;   # no trailing slash — full path preserved
}
After editing:
sudo nginx -t && sudo systemctl reload nginx
Verification:
# Test backend directly (bypassing Nginx)
curl http://localhost:8080/api/sessions
# Should return session list JSON

# Test through Nginx
curl https://your-domain.com/api/sessions
# Should return the same result
Symptom: The browser shows a spinning loader indefinitely, or the browser console shows a WebSocket connection error on wss://your-domain.com/_stcore/stream.Cause: Nginx is missing the WebSocket upgrade headers for Streamlit’s /_stcore/stream endpoint. Without them Nginx cannot pass the protocol upgrade handshake through to the Streamlit container.Fix: Ensure the following location block is present in your Nginx config:
location /_stcore/stream {
    proxy_pass http://127.0.0.1:8501/_stcore/stream;
    proxy_http_version 1.1;

    # Required: WebSocket upgrade headers
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_set_header Host $host;
    proxy_read_timeout 86400;  # Keep WebSocket open for long sessions
}
After adding or correcting the block, reload Nginx:
sudo nginx -t && sudo systemctl reload nginx
Then hard-refresh the browser (Ctrl+Shift+R / Cmd+Shift+R) to force a new WebSocket connection attempt.

​
Local development issues

Symptom: Running python app.py fails with OSError: [Errno 98] Address already in use or ConnectionRefusedError.Diagnosis:
# macOS / Linux
lsof -i :8080

# Windows
netstat -ano | findstr :8080
Fix — kill the occupying process:
# macOS / Linux — kill the process holding port 8080
kill -9 $(lsof -t -i:8080)
Fix — change the port:Edit .env and set a different port, then restart:
PORT=8081
If running in Docker, also update BACKEND_PORT in .env and the proxy_pass port numbers in your Nginx config.
Symptom: The chat interface returns 401 Unauthorized or “API key validation failed” after sending a message.Key format checks:
ProviderExpected prefix
Anthropic Claudesk-ant-api-...
Tavilytvly-...
OpenAIsk-proj-...
Double-check that the key has not been truncated and that there are no leading/trailing spaces in .env.Test that .env is loading correctly:
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('ANTHROPIC_API_KEY'))"
The command should print your key, not None.Docker — verify env vars are passed into the container:
docker exec chatbot-backend env | grep ANTHROPIC_API_KEY
docker exec chatbot-backend env | grep TAVILY_API_KEY
If these return empty, check that the keys are defined in .env and that docker-compose.yml maps them:
backend:
  environment:
    - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    - TAVILY_API_KEY=${TAVILY_API_KEY}

​
Runtime issues

Symptom: The agent starts a search or extract tool call but it times out or returns an error. The streaming response may show a tool error message or stop unexpectedly.Diagnosis:
# Stream backend logs to see the full error stack
docker logs chatbot-backend -f
Common causes and fixes:
  • Network / firewall: Tavily’s API is an external service. Check that outbound HTTPS traffic from the server is not blocked by a firewall or corporate proxy.
  • Tavily API quota exhausted: Log in to app.tavily.com and check your usage. The free tier has monthly request limits.
  • Too many crawl pages: Deep Thinking mode crawls up to 15 pages per query. Reduce crawl_limit or switch to Fast Mode (5-page limit) to stay within quota.
  • Rate limiting: Reduce the number of concurrent requests or add a delay between queries.
Symptom: The assistant’s response begins streaming but cuts off before completing, sometimes mid-sentence.Common causes and fixes:
  • LLM API rate limits or quota: Check your Anthropic / OpenAI dashboard for rate limit errors. The backend logs will show 429 Too Many Requests if this is the case.
  • Nginx proxy timeout: If you are using Nginx, the default proxy_read_timeout (60 s) may expire before the agent finishes. Increase it in the /stream_agent location block: 
    location /stream_agent {
    proxy_read_timeout 300s;  # 5 minutes minimum for long responses
    proxy_buffering off;
    proxy_cache off;
}
    Then reload: sudo nginx -t && sudo systemctl reload nginx
  • Model too large for quota tier: Switch to a lighter model. Claude Haiku is significantly faster and cheaper than Sonnet or Opus and is sufficient for most queries.

​
Data issues

Symptom: After running docker-compose down && docker-compose up -d, all previous conversations are gone from the sidebar.Cause: The data/ directory was not mounted from the host into the container. When the container was removed, its filesystem layer (including data/sessions/) was discarded.Fix: Ensure docker-compose.yml includes the volume mount on the backend service:
backend:
  volumes:
    - ./data:/app/data   # persists session JSON files to the host
After adding the volume, restart:
docker-compose down
docker-compose up -d
Emergency data recovery (if the container is still running):
# Copy session data out of a running container before it is removed
docker cp chatbot-backend:/app/data ./data-backup

​
Performance issues

Symptom: Queries take a long time to complete, especially in Deep Thinking mode.Optimisation checklist:
  1. Use a faster model — Claude Haiku is the fastest and most cost-effective option; Opus is the slowest. Switch in the sidebar model selector.
  2. Use Fast Mode — reduces search results from 5 to 3 and crawl pages from 15 to 5, cutting tool call overhead significantly.
  3. Reduce max_results and crawl limit — in Fast Mode these are already lower; avoid Deep Thinking mode for simple factual questions.
  4. Check server resources — if the host is CPU- or memory-constrained, the containers will be throttled:
docker stats chatbot-backend chatbot-frontend
Look for CPU % consistently near 100% or memory usage approaching the container limit. If so, consider upgrading the server or reducing concurrent users.

​
Log commands

These commands are always useful regardless of which issue you are investigating: 
# Stream backend container logs (last 100 lines then follow)
docker logs chatbot-backend --tail 100 -f

# Stream frontend container logs
docker logs chatbot-frontend --tail 100 -f

# Stream the Nginx error log
sudo tail -f /var/log/nginx/chatbot.error.log

# Real-time CPU and memory usage for both containers
docker stats chatbot-backend chatbot-frontend

# List all containers including stopped ones
docker ps -a

Build docs developers (and LLMs) love

Get started for freeTalk to us