Troubleshooting

Troubleshooting Guide

Last Updated: 2026-02-06 Version: 1.0

Quick Diagnostics

System Health Check

# Check all services
curl http://localhost:8004/api/v1/ready | jq .

# Expected output:
{
  "ready": true,
  "checks": {
    "database": true,
    "vector_store": true,
    "lexical_store": true
  }
}

If any check is false:

database: false → Check PostgreSQL connection
vector_store: false → Check Qdrant status
lexical_store: false → Check OpenSearch status

Service Status

# Check Docker containers
docker ps --filter "name=kb-platform"

# Should show:
# - kb-platform-api (healthy)
# - kb-platform-db (healthy)
# - kb-platform-qdrant (healthy)
# - kb-platform-opensearch (healthy)

Quick Log Check

# API logs (last 50 lines)
docker logs kb-platform-api --tail 50

# Look for:
# - ERROR: Critical issues
# - WARNING: Potential problems
# - INFO: Normal operations

Common Issues

Issue 1: Document Stuck in "Processing" Status

Symptoms:

Document shows status: "processing" for >10 minutes
Progress percentage stuck at same value
No errors in logs

Diagnosis:

# Check document status
curl http://localhost:8004/api/v1/documents/{doc_id}/status | jq .

# Check for errors
docker logs kb-platform-api 2>&1 | grep "ERROR.*{doc_id}"

Common Causes:

Embedding service timeout

# Check logs for:
# "OpenAI API error" or "Ollama connection failed"

Solution: Check embedding service connectivity

Large document (300+ chunks)

# Check progress - if increasing slowly, it's normal
curl http://localhost:8004/api/v1/documents/{doc_id}/status | jq '.progress_percentage'

Solution: Wait longer (can take 2-5 minutes for large docs)

Background task crashed

# Look for stack traces in logs
docker logs kb-platform-api 2>&1 | grep -A 20 "Traceback"

Solution: Reprocess document

curl -X POST http://localhost:8004/api/v1/documents/{doc_id}/reprocess

Issue 2: MCP creates new chats on every request

Symptoms:

MCP or automation calls create many new conversations in the UI
Chat list grows quickly without user interaction

Cause:

MCP is calling POST /chat/, which always creates/updates conversations and messages

Solution:

Use retrieve-only endpoint:
- POST /api/v1/retrieve/
This returns chunks + context without creating conversations

Prevention:

For tools/automation, avoid /chat/ unless you want persistent chat history

Issue 2: Orphaned Chunks in Vector Database

Symptoms:

Qdrant collection size doesn't match expected chunk count
Deleted documents still appear in search results
Collection size keeps growing

Diagnosis:

# Check KB statistics
curl http://localhost:8004/api/v1/knowledge-bases/{kb_id} | jq '{document_count, total_chunks}'

# Compare with Qdrant
curl http://localhost:6334/collections/{collection_name} | jq '.result.vectors_count'

Solution:

# Clean up orphaned chunks
curl -X POST http://localhost:8004/api/v1/knowledge-bases/{kb_id}/cleanup-orphaned-chunks

# Response shows how many chunks were removed
{
  "message": "Cleaned up orphaned chunks",
  "deleted_documents": 5,
  "chunks_removed": 150
}

Prevention:

Always use API delete endpoint (don't manually update database)
Run cleanup periodically in production

Issue 3: Frontend Shows "Processing" but No Progress

Symptoms:

Frontend displays "Processing..." without progress bar
Status doesn't update
Refresh doesn't help

Diagnosis:

# Check if progress fields exist
curl http://localhost:8004/api/v1/documents/{doc_id}/status | jq '{progress_percentage, processing_stage}'

# Should return:
{
  "progress_percentage": 45,
  "processing_stage": "Generating embeddings (100/301)"
}

# If null, backend needs restart or migration

Solutions:

Migration not applied:

# Check current migration
docker exec kb-platform-api alembic current

# Apply missing migrations
docker exec kb-platform-api alembic upgrade head

# Restart API
docker restart kb-platform-api

Frontend caching:
- Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
- Clear browser cache
- Check browser console for errors
Polling not working:
```
// Check browser console for:
// "Failed to poll status for document"
```
- Verify API is accessible from frontend
- Check CORS settings

Issue 4: Semantic Chunking Errors

Symptoms:

Error: "No module 'concurrent.futures'"
Error: "This coroutine should be awaited"
Documents fail with semantic chunking strategy

Diagnosis:

# Check logs for ThreadPoolExecutor errors
docker logs kb-platform-api 2>&1 | grep -i "threadpool\|coroutine"

Solution:

Semantic chunking uses ThreadPoolExecutor for Ollama calls
This is expected behavior and prevents blocking
If errors persist, check Ollama connectivity:
```
curl http://localhost:11434/api/tags
```

Issue 5: High Memory Usage

Symptoms:

API container using >2GB RAM
Slow response times
OOM (Out of Memory) kills

Diagnosis:

# Check container memory
docker stats kb-platform-api --no-stream

# Check active connections
docker exec kb-platform-api ps aux | grep python

Common Causes:

Large documents in memory:
- Limit: 50MB per document
- Solution: Split large files

Too many concurrent processing:

# Check how many documents are processing
curl http://localhost:8004/api/v1/documents/?status=processing | jq '.total'

Limit concurrent uploads to 3-5

Memory leak in embeddings:

# Restart API to free memory
docker restart kb-platform-api

Long-term Solution:

Add memory limits to docker-compose.yml:

services:
  api:
    mem_limit: 2g
    mem_reservation: 1g

Document Processing Problems

Documents Fail Immediately

Symptoms:

Status changes to failed within seconds
Error message in document

Check Error:

curl http://localhost:8004/api/v1/documents/{doc_id} | jq '.error_message'

Common Errors:

"No chunks generated from document"
- Document is empty or unreadable
- Solution: Check file format, re-upload
"Document {id} not found"
- Document was deleted during processing
- Solution: Re-upload document
"Knowledge base {id} not found"
- KB was deleted
- Solution: Create KB first, then upload
"OpenAI API error: Rate limit exceeded"
- Too many requests to OpenAI
- Solution: Wait 60 seconds, use smaller batch_size
"Qdrant connection failed"
- Vector store is down
- Solution: Check Qdrant container
```
docker restart kb-platform-qdrant
```

Progress Stuck at Specific Percentage

35% (Generating embeddings):

Normal for large documents (301 chunks = ~2 minutes)
Check logs for embedding generation progress
If truly stuck >5 minutes, reprocess

80% (Indexing in Qdrant):

Qdrant may be slow with large batches

Check Qdrant logs:

docker logs kb-platform-qdrant --tail 50

90% (Indexing BM25):

OpenSearch may be slow or unavailable

Check OpenSearch:

curl http://localhost:9200/_cluster/health

If OpenSearch is down, BM25 will fail but embeddings still work

Chunking Strategy Issues

Fixed Size:

Fast, reliable
May break sentences awkwardly

Smart (Recursive):

Balanced performance
Respects sentence boundaries
Recommended for most use cases

Semantic:

Slow for large documents (uses embeddings)
Requires Ollama or OpenAI for sentence embeddings
Best quality but highest cost/time

Check Ollama status if using local embeddings:

curl http://localhost:8004/api/v1/ollama/status

Performance Issues

Slow API Responses

Diagnosis:

# Test endpoint latency
time curl http://localhost:8004/api/v1/health

# Should be < 100ms

Common Causes:

Slow database queries:

# Check PostgreSQL performance
docker exec kb-platform-db psql -U kb_user -d knowledge_base -c "
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;"

Too many documents in KB:
- Pagination helps but large KBs (1000+ docs) are slower
- Solution: Add database indexes (already included in migrations)
Qdrant collection too large:
```
# Check collection size
curl http://localhost:6334/collections/{collection_name}
```
- Collections with >100k vectors may be slow
- Solution: Consider sharding or multiple KBs

Slow Search/Retrieval

Symptoms:

Chat queries take >3 seconds
High CPU on Qdrant

Diagnosis:

# Test search performance
time curl -X POST http://localhost:8004/api/v1/chat/ \
  -H "Content-Type: application/json" \
  -d '{"question":"test","knowledge_base_id":"..."}'

Optimization:

Reduce top_k:
```
{
  "top_k": 3  // Instead of 10
}
```

Use dense-only retrieval:

{
  "retrieval_mode": "dense"  // Faster than hybrid
}

Optimize Qdrant:
- HNSW parameters are already tuned in code
- For very large collections, consider quantization

Database Issues

Issue: Multiple head revisions during migration

Symptoms:

API контейнер перезапускается и миграции падают
В логах: Multiple head revisions are present for given argument 'head'

Cause:

В репозитории несколько heads Alembic (несведенные ветки)

Solution:

Добавить merge‑миграцию и пересобрать образ
Затем alembic upgrade head

Migration Errors

Error: "Target database is not up to date"

# Check current version
docker exec kb-platform-api alembic current

# Show migration history
docker exec kb-platform-api alembic history

# Apply all migrations
docker exec kb-platform-api alembic upgrade head

Error: "Can't locate revision"

# Reset migrations (DANGER: only for non-production)
docker exec kb-platform-api alembic downgrade base
docker exec kb-platform-api alembic upgrade head

Database Connection Issues

Error: "could not connect to server"

Check PostgreSQL:

docker logs kb-platform-db --tail 20

# Test connection
docker exec kb-platform-db pg_isready -U kb_user

Solution:

# Restart database
docker restart kb-platform-db

# Wait for health check
docker ps --filter "name=kb-platform-db"

Orphaned Records

Documents without Knowledge Base:

-- Connect to database
docker exec -it kb-platform-db psql -U kb_user -d knowledge_base

-- Find orphans
SELECT id, filename FROM documents
WHERE knowledge_base_id NOT IN (SELECT id FROM knowledge_bases);

-- Clean up (careful!)
DELETE FROM documents
WHERE knowledge_base_id NOT IN (SELECT id FROM knowledge_bases);

Chunks without Documents:

Use cleanup endpoint (see Issue 2 above)

Vector Store Issues

Qdrant Connection Failed

Symptoms:

/ready shows vector_store: false
Documents fail with Qdrant errors

Diagnosis:

# Check Qdrant health
curl http://localhost:6334/health

# Should return: {"status":"ok"}

Solutions:

Qdrant not running:

docker ps | grep qdrant
docker start kb-platform-qdrant

Port conflict:

# Check if port 6334 is in use
netstat -tlnp | grep 6334

Qdrant corrupted:

# Restart Qdrant
docker restart kb-platform-qdrant

# If still failing, recreate (loses data!)
docker-compose down qdrant
docker volume rm kb_qdrant_data
docker-compose up -d qdrant

Collection Not Found

Error: "Collection {name} not found"

Diagnosis:

# List collections
curl http://localhost:6334/collections | jq '.result.collections[].name'

Solution:

Collections are auto-created on first document upload
If missing, re-upload a document to the KB
Collection name format: kb_{hash} (check KB details)

Vector Count Mismatch

Symptoms:

total_chunks in PostgreSQL ≠ vectors in Qdrant

Check:

# PostgreSQL
curl http://localhost:8004/api/v1/knowledge-bases/{kb_id} | jq '.total_chunks'

# Qdrant
curl http://localhost:6334/collections/{collection_name} | jq '.result.vectors_count'

Solution:

Run cleanup endpoint (see Issue 2)

If still mismatch, reprocess all documents:

curl -X POST http://localhost:8004/api/v1/knowledge-bases/{kb_id}/reprocess

API Issues

500 Internal Server Error

Diagnosis:

# Check recent errors
docker logs kb-platform-api --tail 100 2>&1 | grep ERROR

# Look for stack trace
docker logs kb-platform-api 2>&1 | grep -A 30 "Traceback"

Common Causes:

Database connection lost:
- Restart API: docker restart kb-platform-api
Unhandled exception:
- Check logs for specific error
- May need code fix
Out of memory:
- Check memory usage: docker stats kb-platform-api

503 Service Unavailable

Diagnosis:

# Check /ready endpoint
curl http://localhost:8004/api/v1/ready | jq .

Solution:

One or more dependencies are down
Fix the failing service (database, Qdrant, OpenSearch)

422 Validation Error

Example:

{
  "detail": [
    {
      "loc": ["body", "knowledge_base_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Solution:

Check request body against API documentation
Common mistakes:
- Missing required fields
- Wrong field types
- Invalid enum values

Frontend Issues

Frontend Won't Load

Symptoms:

Blank page
"Cannot connect to server"

Diagnosis:

# Check frontend container (nginx health)
curl http://localhost:5174/health

# Check API from frontend perspective
curl http://localhost:8004/api/v1/health

Solutions:

Frontend container not running:

docker compose ps
docker compose up -d --build frontend
docker compose logs -f frontend

Wrong port:
- Check docker-compose.yml port mappings
- Default UI port: 5174
CORS errors:
- Check browser console
- Verify CORS_ORIGINS in .env includes the UI origin (e.g., http://localhost:5174)

"Network Error" in Frontend

Symptoms:

Requests fail with network error
Console shows CORS errors

Check CORS:

# Test CORS
curl -H "Origin: http://localhost:5174" \
  -H "Access-Control-Request-Method: POST" \
  -X OPTIONS \
  http://localhost:8004/api/v1/chat/

Solution:

Update .env:

CORS_ORIGINS=http://localhost:5174,http://localhost:3000

Restart API

Monitoring & Observability

Key Metrics to Monitor

System Health:

# Every 1 minute
curl http://localhost:8004/api/v1/ready

Processing Queue:

# Every 5 minutes
curl http://localhost:8004/api/v1/documents/?status=processing | jq '.total'

# Alert if > 10 documents stuck in processing

Error Rate:

# Check logs for errors per hour
docker logs kb-platform-api --since 1h 2>&1 | grep -c ERROR

# Alert if > 50 errors/hour

Database Size:

# Check PostgreSQL database size
docker exec kb-platform-db psql -U kb_user -d knowledge_base -c "
SELECT pg_size_pretty(pg_database_size('knowledge_base'));"

Qdrant Size:

# Check all collections
curl http://localhost:6334/collections | jq '.result.collections[] | {name, vectors_count}'

Log Analysis

Find slow queries:

docker logs kb-platform-api 2>&1 | grep "took.*ms" | sort -t'=' -k2 -n | tail -20

Find failed documents:

docker logs kb-platform-api 2>&1 | grep "Failed to process document" | tail -20

Find rate limit errors:

docker logs kb-platform-api 2>&1 | grep "Rate limit" | tail -20

Recovery Procedures

Complete System Reset (Development Only)

# Stop all services
docker-compose down

# Remove all data
docker volume rm kb_postgres_data kb_qdrant_data kb_opensearch_data

# Rebuild and restart
docker-compose up -d

# Apply migrations
docker exec kb-platform-api alembic upgrade head

Restore from Backup (Production)

PostgreSQL:

# Backup
docker exec kb-platform-db pg_dump -U kb_user knowledge_base > backup.sql

# Restore
cat backup.sql | docker exec -i kb-platform-db psql -U kb_user knowledge_base

Qdrant:

# Backup (snapshot)
curl -X POST http://localhost:6334/collections/{collection_name}/snapshots

# List snapshots
curl http://localhost:6334/collections/{collection_name}/snapshots

# Restore
# Copy snapshot file to Qdrant data directory and restart

Reprocess All Documents in KB

# Reprocess entire KB (use with caution)
curl -X POST http://localhost:8004/api/v1/knowledge-bases/{kb_id}/reprocess

# Monitor progress
watch -n 5 "curl -s http://localhost:8004/api/v1/documents/?knowledge_base_id={kb_id} | jq '.items[] | {filename, status}'"

Known Limitations

File Size

Maximum: 50 MB per file
Reason: Memory constraints during processing
Workaround: Split large files

Concurrent Processing

Recommended: Max 5 documents processing simultaneously
Reason: Embedding API rate limits, memory usage
Workaround: Queue uploads, wait for completion

Vector Search

Optimal: < 100k vectors per collection
Maximum: 1M+ vectors (but slower)
Workaround: Multiple knowledge bases, sharding

Semantic Chunking

Speed: ~2-5 minutes for 300-chunk document
Reason: Sentence embedding generation
Workaround: Use "smart" chunking for faster processing

OpenSearch (BM25)

Optional: System works without it (dense-only retrieval)
If unavailable: Hybrid search falls back to dense
No impact: On core functionality

Getting Help

Before Reporting Issues

✅ Check this troubleshooting guide
✅ Check API logs: docker logs kb-platform-api --tail 100
✅ Check /ready endpoint
✅ Try restarting services
✅ Check API Documentation

Report Format

When reporting issues, include:

**Environment:**
- OS:
- Docker version:
- API version: (from /info endpoint)

**Issue:**
- What were you trying to do?
- What happened instead?
- Error messages:

**Logs:**
```bash
docker logs kb-platform-api --tail 50

Steps to Reproduce: 1. 2. 3.

Additional Context:

Document size:
Knowledge base size:
Concurrent operations:


---

**Last Updated:** 2026-02-06
**Need more help?** [Open an issue](https://github.com/loglux/RAG-Knowledge-Base-Platform/issues)

📝 Questions? Open an issue | 🌟 Like it? Star the repo | 📖 API Docs: Swagger UI

📚 Documentation

Getting Started

🏠 Home

API Reference

Operations

🔧 Troubleshooting Guide

Links

Version: v1.0
Updated: 2026-02-08

Troubleshooting

Troubleshooting Guide

Table of Contents

Quick Diagnostics

System Health Check

Service Status

Quick Log Check

Common Issues

Issue 1: Document Stuck in "Processing" Status

Issue 2: MCP creates new chats on every request

Issue 2: Orphaned Chunks in Vector Database

Issue 3: Frontend Shows "Processing" but No Progress

Issue 4: Semantic Chunking Errors

Issue 5: High Memory Usage

Document Processing Problems

Documents Fail Immediately

Progress Stuck at Specific Percentage

Chunking Strategy Issues

Performance Issues

Slow API Responses

Slow Search/Retrieval

Database Issues

Issue: Multiple head revisions during migration

Migration Errors

Database Connection Issues

Orphaned Records

Vector Store Issues

Qdrant Connection Failed

Collection Not Found

Vector Count Mismatch

API Issues

500 Internal Server Error

503 Service Unavailable

422 Validation Error

Frontend Issues

Frontend Won't Load

"Network Error" in Frontend

Monitoring & Observability

Key Metrics to Monitor

Log Analysis

Recovery Procedures

Complete System Reset (Development Only)

Restore from Backup (Production)

Reprocess All Documents in KB

Known Limitations

File Size

Concurrent Processing

Vector Search

Semantic Chunking

OpenSearch (BM25)

Getting Help

Before Reporting Issues

Report Format

Uh oh!

Uh oh!

Uh oh!

Uh oh!

📚 Documentation

Getting Started

API Reference

Operations

Links

Clone this wiki locally