Troubleshooting¶

This guide helps diagnose and resolve common issues with the RAG Chatbot.

Quick Diagnostics¶

System Health Check¶

Run these commands to verify all components:

# Check web server
curl -I http://localhost/chatbot/public/

# Check database connection
psql -h localhost -U raguser -d ragdb -c "SELECT 1;"

# Check Docling service
curl http://localhost:8001/health

# Check PHP-FPM
sudo systemctl status php-fpm

View Recent Errors¶

# PHP errors
sudo tail -50 /var/log/php-fpm/www-error.log

# Apache errors
sudo tail -50 /var/log/httpd/chatbot-error.log

# Application logs
ls -la /var/www/chatbot/logs/

Chat Issues¶

"I don't have enough information to answer that question"¶

Cause: No relevant documents match the query.

Solutions:

1. Verify documents are uploaded:

curl "http://localhost/chatbot/public/debug-rag.php"

1. Test the search directly:

curl "http://localhost/chatbot/public/debug-rag.php?query=your+question"

1. Lower the search threshold:

curl "http://localhost/chatbot/public/debug-rag.php?query=your+question&threshold=0.2"

1. Check if embeddings exist:

SELECT COUNT(*) FROM embeddings;

Slow Responses¶

Possible causes:

Database optimization:

-- Analyze tables
VACUUM ANALYZE documents;
VACUUM ANALYZE chunks;
VACUUM ANALYZE embeddings;

-- Check index usage
SELECT indexrelname, idx_scan, idx_tup_read
FROM pg_stat_user_indexes
WHERE schemaname = 'public';

Rate Limit Errors (429)¶

Cause: Too many requests from same session/IP.

Solutions:

1. Wait for the window to reset (check Retry-After header)
2. Increase limits in code if legitimate traffic
3. Use different session IDs for different users

Upload Issues¶

"File type not allowed"¶

Cause: Extension not in whitelist.

Solution: Check supported formats in Uploading Documents.

"Document parsing service unavailable"¶

Cause: Docling service is not running or unreachable.

Check:

# Is the service running?
docker ps | grep docling

# Can you reach it?
curl http://localhost:8001/health

# Check logs
docker logs docling-service

Solutions:

1. Start the service: docker compose up -d
2. Check firewall allows port 8001
3. Verify DOCLING_SERVICE_URL in .env

Upload Timeout¶

Cause: Large file or slow processing.

Solutions:

1. Increase timeout in .env:

DOCLING_TIMEOUT=600

1. Increase PHP timeout:

; In php.ini
max_execution_time = 300

1. Increase web server timeout (Apache):

TimeOut 300

"No transcript available" (Media Import)¶

Cause: Video has no subtitles and transcription failed.

Solutions:

1. Check if the video has subtitles on the platform
2. Ensure Docling has transcription models loaded
3. Try different subtitle languages

Database Issues¶

Connection Refused¶

Symptoms: "could not connect to server"

Check:

# Is PostgreSQL running?
sudo systemctl status postgresql-16

# Is it listening?
ss -tlnp | grep 5432

# Check pg_hba.conf
sudo cat /var/lib/pgsql/16/data/pg_hba.conf

Solutions:

1. Start PostgreSQL: sudo systemctl start postgresql-16
2. Update pg_hba.conf to allow connections
3. Check DB_HOST in .env matches actual host

pgvector Extension Missing¶

Symptoms: "type vector does not exist"

Solution:

# Reinstall pgvector
cd /tmp/pgvector
make clean
make
sudo make install

# Enable in database
sudo -u postgres psql -d ragdb -c "CREATE EXTENSION vector;"

Slow Queries¶

Diagnose:

-- Find slow queries
SELECT query, calls, mean_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

-- Check if HNSW index is used
EXPLAIN ANALYZE
SELECT * FROM embeddings
ORDER BY embedding <=> '[0.1,0.2,...]'::vector
LIMIT 5;

Solutions:

-- Rebuild indexes
REINDEX TABLE embeddings;

-- Update statistics
ANALYZE embeddings;

-- Increase work_mem for complex queries
SET work_mem = '256MB';

LLM Provider Issues¶

OpenAI API Errors¶

"Invalid API key":

1. Verify key in .env
2. Check key hasn't expired
3. Ensure no extra whitespace

"Rate limit exceeded":

1. Check your OpenAI usage dashboard
2. Upgrade your plan if needed
3. Implement request queuing

"Model not found":

1. Verify model name in .env
2. Check you have access to the model
3. Use a valid model: gpt-4, gpt-4-turbo, gpt-3.5-turbo

Claude API Errors¶

"Authentication failed":

1. Verify ANTHROPIC_API_KEY
2. Check key format starts with sk-ant-

Test API directly:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'

Docling Service Issues¶

Container Won't Start¶

Check logs:

docker compose logs docling

Common issues:

GPU Not Detected¶

Verify GPU access:

# Check NVIDIA driver
nvidia-smi

# Test Docker GPU access
docker run --rm --gpus all nvidia/cuda:11.8-base nvidia-smi

Solutions:

1. Install nvidia-container-toolkit
2. Restart Docker: sudo systemctl restart docker
3. Set DOCLING_DEVICE_MODE=cuda explicitly

OCR Not Working¶

Check:

# Verify OCR is enabled
grep DOCLING_ENABLE_OCR .env

# Check OCR language
grep DOCLING_OCR_LANGUAGE .env

Solutions:

1. Enable OCR: DOCLING_ENABLE_OCR=true
2. Set correct language: DOCLING_OCR_LANGUAGE=en
3. Ensure image quality is sufficient

Chat Widget Issues¶

Widget Not Loading¶

Check browser console for errors (F12 → Console)

Common issues:

Widget Styling Broken¶

Solutions:

1. Check for CSS conflicts with your site
2. Ensure widget CSS isn't being overridden
3. Try loading widget in an iframe

Session Not Persisting¶

Cause: localStorage blocked or cleared.

Solutions:

1. Check if localStorage is available
2. Verify cookies aren't being blocked
3. Check for browser privacy settings

Performance Issues¶

High Memory Usage¶

Check:

# System memory
free -h

# PHP-FPM memory
ps aux | grep php-fpm

# PostgreSQL memory
ps aux | grep postgres

Solutions:

1. Reduce PHP-FPM workers
2. Lower PostgreSQL shared_buffers
3. Limit Docling concurrent jobs

High CPU Usage¶

Identify the cause:

top -c

Common culprits:

Getting Help¶

Information to Gather¶

When seeking help, provide:

1. Error messages - Exact text from logs
2. Steps to reproduce - What you did
3. Environment - OS, PHP version, PostgreSQL version
4. Configuration - Relevant .env settings (redact secrets!)

Log Locations¶

Debug Mode¶

Enable verbose logging temporarily:

# In .env
API_DEBUG_LOGGING_ENABLED=true

Access debug logs at /api-debug/logs (requires authentication).