Troubleshooting

This page covers common issues you may encounter when running KaaS, along with their possible causes and solutions.

LLM Connection Failed

Symptoms: Compilation fails immediately with connection errors; logs show LLM request failed or timeout messages.

Possible Causes:

• Incorrect or missing API key
• Wrong base_url configuration
• Network issues (firewall, proxy, DNS)

Solution:

1. Verify your environment variables are set correctly:

   echo $KAAS_LLM_API_KEY
   echo $KAAS_LLM_BASE_URL

2. Test connectivity to the LLM endpoint directly:

   curl -s -o /dev/null -w "%{http_code}" \
     -H "Authorization: Bearer $KAAS_LLM_API_KEY" \
     "$KAAS_LLM_BASE_URL/models"

   A 200 response confirms the endpoint is reachable.

3. If behind a proxy, ensure HTTP_PROXY / HTTPS_PROXY are configured.

4. Check that your API key has not expired or hit its rate limit.

---

Compilation Stuck / No Progress

Symptoms: The compilation process appears to hang; no new articles are generated for an extended period.

Possible Causes:

• Circuit breaker tripped due to repeated LLM failures
• Worker lease expired (worker timed out waiting for LLM response)
• LLM endpoint is responding extremely slowly

Solution:

1. Check the backend logs for circuit breaker messages:

   docker logs kaas-backend 2>&1 | grep -i "circuit"

2. If the circuit breaker has tripped, it will reset automatically after the cooldown period. You can adjust these settings:

   [compiler]
   cb_failure_threshold = 5   # failures before tripping
   cb_cooldown_sec = 60       # seconds before retry

3. Verify the LLM endpoint is still responsive (see LLM Connection Failed).

4. If workers have timed out, restart the compilation:

   kaas compile --resume

---

MCP Connection Refused

Symptoms: MCP clients cannot connect to KaaS; errors like connection refused on the MCP port.

Possible Causes:

• KAAS_MCP_ENABLED environment variable not set to true
• Incorrect port configuration or port not exposed
• Token mismatch between client and server

Solution:

1. Ensure MCP is enabled in your configuration:

   export KAAS_MCP_ENABLED=true

2. Verify the MCP port is correctly mapped (default: 8081):

   # If using Docker
   docker ps --format "table {{.Ports}}" | grep kaas

3. Test the MCP endpoint:

   curl -v http://localhost:8081/health

4. Confirm the token matches between your MCP client config and KaaS:

   echo $KAAS_MCP_TOKEN

   The token in your client's MCP configuration must match this value exactly.

---

Docker Container Won't Start

Symptoms: docker compose up exits immediately or the container enters a restart loop.

Possible Causes:

• Port conflict (another service is using port 8080 or 8081)
• Missing required environment variables
• Volume mount permission issues

Solution:

1. Check container logs for the specific error:

   docker logs kaas-backend

2. Check for port conflicts:

   lsof -i :8080
   lsof -i :8081

   If another process occupies the port, stop it or change KaaS's port mapping in docker-compose.yml.

3. Ensure all required environment variables are set. At minimum:

   KAAS_LLM_API_KEY=your-key
   KAAS_LLM_BASE_URL=https://api.openai.com/v1

4. Verify data directory permissions:

   ls -la ./data/
   # The directory must be writable by the container user (UID 1000)
   chmod -R 755 ./data/

---

Wiki Is Empty After Compilation

Symptoms: Compilation reports success but no articles appear in the wiki; the knowledge base has zero entries.

Possible Causes:

• Source content too short to extract meaningful knowledge
• Wrong kb_dir path configured
• Compilation actually failed silently (partial failure)

Solution:

1. Check the Status page or API for compilation results:

   curl http://localhost:8080/api/v1/status

2. Verify the data directory contains generated markdown files:

   ls ./data/*.md 2>/dev/null | wc -l

3. Check backend logs for extraction warnings:

   docker logs kaas-backend 2>&1 | grep -i "skip\|empty\|too short"

4. Ensure kb_dir in your config points to the correct source directory:

   [compiler]
   kb_dir = "./data"

5. If source documents are very short (< 100 characters), KaaS may skip them. Consider consolidating small documents.

---

Chat Returns "No relevant articles found"

Symptoms: The chat interface responds with "No relevant articles found" even for topics that should be covered.

Possible Causes:

• Wiki has not been compiled yet
• Master index is missing or corrupted
• Query is too vague or uses different terminology than the source material

Solution:

1. Confirm compilation has completed successfully:

   curl http://localhost:8080/api/v1/status
   # Look for "compilation_status": "completed"

2. Verify the data directory has markdown files and a master index:

   ls ./data/*.md
   ls ./data/master-index*

3. If the index is missing, re-run compilation:

   kaas compile

4. Try a more specific query that uses terms directly from your source documents.

---

Slow Compilation Performance

Symptoms: Compilation takes much longer than expected; progress is very slow but not stuck.

Possible Causes:

• Model too large or slow for available hardware (when using local LLM)
• Too few extraction workers configured
• High network latency to the LLM API

Solution:

1. Increase the number of workers:

   [compiler]
   extract_workers = 4   # default is 2; increase based on API rate limits

2. If using a remote API, check latency:

   time curl -s -o /dev/null "$KAAS_LLM_BASE_URL/models"

3. Consider using a faster or smaller model for extraction:

   [llm]
   model = "gpt-4o-mini"   # faster than gpt-4o for extraction tasks

4. If running a local LLM, ensure you have sufficient GPU memory and that the model fits without excessive swapping.

5. Monitor system resources during compilation:

   docker stats kaas-backend