Troubleshooting

This guide covers the most common issues you'll encounter while building and deploying RAG systems, with concrete fixes for each scenario.

Upload Failures

File Too Large

Error: File size exceeds 50MB limit

Cause: Single file exceeds the maximum allowed size.

Fix: Split large PDFs or compress images before uploading.

# Split PDF by pages (requires qpdf)
qpdf input.pdf --pages . 1-50 -- part1.pdf
qpdf input.pdf --pages . 51-100 -- part2.pdf
 
# Compress images
convert input.png -quality 80 output.png

Unsupported File Format

Error: Unsupported file type: .xyz

Supported formats:

Fix: Convert unsupported formats to one of the supported types above.

Upload Timeout

Error: Request timeout after 30s

Cause: Large file upload exceeded the default timeout.

Fix: Use the POST /rag/upload-and-process endpoint with multipart form data, which streams the upload:

curl -X POST "https://api.guidedmind.ai/rag/upload-and-process" \
  -H "X-API-Key: rk_your_key_here" \
  -F "file=@large_document.pdf" \
  -F "project_id=proj_abc123"

Processing Errors

Low Similarity Scores

Symptom: Search results return scores below 0.3 for queries that should match.

Diagnosis: Use the Similarity Score Test to identify the root cause.

Common causes and fixes:

Documents Not Appearing in Search

Checklist:

1. Verify document status is processed (not uploading or failed)
2. Confirm the document belongs to the correct project
3. Check that the search query uses natural language (not keywords)
4. Lower the threshold parameter to see more results

# Test with low threshold to see all available chunks
curl -X POST "https://api.guidedmind.ai/rag/search" \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "test",
    "options": {
      "threshold": 0.1,
      "limit": 20
    }
  }'

Duplicate Chunks

Symptom: Same content appears multiple times in search results.

Cause: Overlapping chunks with high chunk_overlap value, or duplicate documents uploaded.

Fix:

1. Reduce chunk_overlap to 50-100
2. Check for duplicate files in your data source
3. Use the Chunk Review Tool to preview chunk boundaries

Rate Limiting

Understanding Rate Limits

Handling 429 Errors

Error Response:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 30 seconds.",
  "retry_after": 30
}

Fix: Implement exponential backoff:

import time
import requests
 
def search_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.guidedmind.ai/rag/search",
            headers={"X-API-Key": "rk_your_key_here"},
            json={"query": query}
        )
        
        if response.status_code == 429:
            retry_after = response.json().get("retry_after", 30)
            wait_time = retry_after * (2 ** attempt)
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
            
        return response.json()
    
    raise Exception("Max retries exceeded")

API Key Issues

Invalid API Key

Error:

{
  "error": "authentication_failed",
  "message": "Invalid or expired API key"
}

Fix:

1. Verify your API key starts with rk_
2. Check for trailing whitespace when copying
3. Regenerate from the dashboard if lost

API Access Disabled

Error:

{
  "error": "access_denied",
  "message": "API access is not enabled for this project"
}

Fix: Enable API access in Step 5 of the RAG Wizard (API Endpoints tab), or contact support to enable it for existing projects.

Key Permissions

Each API key is scoped to a specific project. You cannot use Project A's key to access Project B's data.

# This will fail if the key belongs to a different project
curl -X POST "https://api.guidedmind.ai/rag/search" \
  -H "X-API-Key: rk_wrong_project_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "test"}'
# → 403 Forbidden

MCP Connection Issues

SSE Connection Fails

Error: Failed to establish SSE connection

Checklist:

1. Verify your base URL includes /api/v1/mcp/sse
2. Confirm your API key is passed as a query parameter
3. Check that your client supports SSE (Server-Sent Events)

# Correct connection format
curl -N "https://api.guidedmind.ai/api/v1/mcp/sse?api_key=rk_your_key_here"
 
# Expected response
# event: open
# data: {"session_id": "uuid-here", "message_endpoint": "/api/v1/mcp/messages?session_id=uuid-here"}

Messages Not Received

Symptom: SSE connection opens but no tool results return.

Fix: Ensure you're sending messages to the correct message_endpoint from the SSE open event:

# Step 1: Get session_id from SSE open event
# (message_endpoint from step 1)
 
# Step 2: Send to the correct endpoint
curl -X POST "https://api.guidedmind.ai/api/v1/mcp/messages?session_id=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "rag_search",
      "arguments": {
        "query": "What is RAG?"
      }
    }
  }'

JSON-RPC Errors

Error: {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}}

Cause: Invalid method name in JSON-RPC request.

Valid methods:

Search Quality Issues

Irrelevant Results

Symptom: Search returns chunks unrelated to the query.

Iteration steps:

1. Test different embedding models:

   • text-embedding-3-small — Fast, good for general content
   • text-embedding-3-large — Best quality, use for technical/legal
   • all-MiniLM-L6-v2 — Lightweight, good for simple queries

2. Adjust chunking:

   • Smaller chunks (250-500) — More precise matches
   • Larger chunks (1000-2000) — Better context retention

3. Try Hybrid search: Combines dense (embedding) + sparse (BM25) for best coverage

Empty Results

Symptom: Search returns zero results.

Checklist:

1. Documents are processed (not stuck in uploading state)
2. Threshold is not too high (try 0.3 as starting point)
3. Query uses natural language, not single keywords
4. Project has at least one processed document

# Diagnostic query with minimal filtering
curl -X POST "https://api.guidedmind.ai/rag/search" \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "anything",
    "options": {
      "threshold": 0.0,
      "limit": 5
    }
  }'

Getting Help

If you're still stuck after trying the fixes above:

1. Check your project logs in the dashboard for processing errors
2. Use the Pipeline Test Tool to isolate configuration issues
3. Contact support with your project ID and a description of the issue