roboco/docs/rag/troubleshooting/kb-errors.md

Knowledge Base Troubleshooting

Empty Search Results

Problem: roboco_kb_search() returns nothing

Causes:

1. Content not indexed yet
2. Query too specific
3. Wrong index type filter

Solutions:

• Check what's indexed: roboco_kb_stats()
• Broaden query terms
• Remove index_types filter
• Trigger reindex: roboco_reindex_all()

Empty RAG Response

Problem: roboco_rag_query() returns empty answer

Causes:

1. No relevant context found
2. LLM returned thinking tags only
3. Query too vague

Solutions:

• Check KB has relevant content
• Rephrase query to be more specific
• Use roboco_kb_search() first to verify content exists

Mentor Not Responding

Problem: roboco_ask_mentor() fails or empty

Causes:

1. LLM timeout
2. No relevant KB content
3. Service temporarily unavailable

Solutions:

• Retry the query
• Check KB stats
• Use roboco_kb_search() as fallback

Index Failed

Problem: roboco_kb_index_code() or roboco_kb_index_docs() fails

Causes:

1. Invalid file patterns
2. Files not accessible
3. Embedding service down

Solutions:

• Verify file patterns match files
• Check file permissions
• Verify Ollama is running

Documentation Write Failed

Problem: roboco_docs_write() fails

Causes:

1. Invalid doc_type (must be: api, qa, guide, readme, changelog, architecture, design)
2. Missing required fields (task_id, filename, title, content)
3. Agent not authorized (only documenter and cell_pm roles)
4. Task not found

Solutions:

• Verify doc_type is valid
• Ensure all required fields provided
• Check your role has write permission
• Verify task_id exists

Duplicate Documentation Created

Problem: Created duplicate docs instead of updating existing

Causes:

1. Content too different from existing doc (RAG similarity < 0.75)
2. Doc in different team folder
3. RAG search failed (but write still succeeded)

Solutions:

• Ensure content covers same topic as existing doc
• Check existing docs first: roboco_docs_list(task_id)
• Search KB: roboco_kb_search("topic keywords")
• Delete duplicate if needed: roboco_docs_delete(path)

Note: roboco_docs_write() uses RAG to auto-deduplicate by content similarity (not just title). If content is semantically similar (>75% similarity), it updates instead of creating new.

Cannot Clear Index

Problem: "Not authorized to clear index"

Cause: Only PM/CEO can clear indexes

Solution: Ask PM or CEO to clear if needed

Proactive Context Empty

Problem: roboco_get_proactive_context() returns empty

Cause: No relevant context found for task

Solution: Manual search with roboco_kb_search() using task keywords