Knowledge Base Troubleshooting

Fix common issues with document uploads, web crawling, and processing. This guide covers failed documents, stuck processing, and retrieval problems.

Check status: Open your Knowledge Base to view document statuses and error messages.

Document Status Quick Reference

Failed Documents

Viewing Error Details

1. Find the failed document in your knowledge base
2. Click the info icon (ℹ️) next to the error badge
3. View the full error message and metadata

Retrying Failed Documents

1. Click the Retry button next to the failed document
2. The document will re-process from the beginning
3. Monitor status until completed

Common Failure Causes

"No content extracted"

Cause: Document has no extractable text.

Solutions:

• PDF: Ensure it's text-based, not scanned images
• URL: Check if page content loads without JavaScript
• Empty file: Verify file actually contains content

"Embedding failed" / "OpenAI API error"

Cause: Failed to generate vector embeddings.

Solutions:

• Wait a few minutes and retry (temporary API issues)
• Check if document contains valid text
• Contact support if persists

"Invalid file format"

Cause: Unsupported or corrupted file.

Solutions:

• Convert to supported format (PDF, DOCX, TXT, MD, CSV)
• Re-export the file from original application
• Check file isn't password-protected

"File too large"

Cause: File exceeds 50 MB limit.

Solutions:

• Split into smaller files
• Remove embedded images/media
• Compress the document

"Failed to crawl URL"

Cause: Could not fetch web page.

Solutions:

• Verify URL is accessible in browser
• Check if site blocks crawlers (robots.txt)
• Ensure URL doesn't require login
• Try a different page from the same site

Stuck Documents

Documents in "Processing" for more than 10 minutes are automatically marked as "Stuck" with a yellow warning badge.

Why Documents Get Stuck

Fixing Stuck Documents

1. Identify: Look for yellow "Stuck" badge
2. Retry: Click the Retry button
3. Monitor: Watch for completion
4. Split: If fails again, try splitting the document

Automatic Cleanup

The system runs a background cleanup process that:

• Checks for documents stuck > 30 minutes
• Marks them as "Failed" for manual retry
• This happens automatically, no action needed

Upload Issues

"Upload failed"

Check:

1. File size under 50 MB?
2. Supported format (PDF, DOCX, TXT, MD, CSV)?
3. Internet connection stable?
4. File not corrupted?

"Processing takes forever"

Normal processing times:

If exceeding these times:

• Large files take longer - be patient
• If stuck > 10 minutes, you'll see "Stuck" badge
• Retry if stuck

"Document shows 0 chunks"

Cause: No content was extracted from the document.

Solutions:

• Check document isn't empty
• For PDFs: Ensure text-based, not scanned images
• For URLs: Verify content loads without JavaScript
• Try a different document to test

Web Crawling Issues

"Sitemap not found"

Solutions:

1. Try direct sitemap URL: https://site.com/sitemap.xml
2. Check robots.txt for sitemap location
3. Use single URL mode instead

"Page blocked by robots.txt"

Cause: Website disallows crawling.

Solutions:

• Respect the site's wishes (it's their policy)
• Use file upload instead
• Contact site owner for permission

"No content extracted from URL"

Causes:

• JavaScript-rendered content (SPA)
• Page requires login
• Content in iframes

Solutions:

• Try a different page
• Use file upload for this content
• Export page to PDF and upload

"Crawl rate limited"

Cause: Too many requests too fast.

Solutions:

• Increase crawl delay (default is 2 seconds)
• Reduce number of pages per crawl
• Wait and retry later

Retrieval Issues

"Agent doesn't find information"

Check:

1. Document processed? Status should be "Completed"
2. Chunks exist? Check chunk count > 0
3. RAG configured? Agent has knowledge base linked
4. Question matches content? Test with exact phrases from doc

"Wrong information retrieved"

Solutions:

1. Lower minScore threshold (try 0.5)
2. Increase topK (retrieve more chunks)
3. Improve document quality
4. Use more specific document content

See RAG Integration for configuration.

"Too much irrelevant information"

Solutions:

1. Raise minScore threshold (try 0.8)
2. Decrease topK (retrieve fewer chunks)
3. Split documents by topic
4. Remove unrelated content

Performance Issues

Slow Processing

For file uploads:

• Split large files into smaller ones
• Remove unnecessary images/media
• Use simpler formats (TXT vs PDF)

For web crawling:

• Reduce pages per crawl
• Use single URL mode for testing
• Increase crawl delay

High Failure Rate

If many documents are failing:

1. Check for common pattern in errors
2. Verify account has valid API keys
3. Try one document at a time
4. Contact support if systematic issue

Error Messages Reference

Getting Help

Before Contacting Support

Gather this information:

1. Document ID (shown in error details)
2. Error message (full text)
3. File type and size
4. Steps to reproduce
5. Screenshot of the issue

Self-Service Options

1. Retry: Many issues resolve with a simple retry
2. Re-upload: Delete and re-upload the document
3. Alternative format: Try PDF → TXT conversion
4. Split files: Break large documents into parts

Contact Support

If issues persist:

• Email: [email protected]
• Include: Error details, document ID, screenshots

Best Practices to Avoid Issues

Document Preparation

• Use text-based PDFs (not scans)
• Keep files under 10 MB when possible
• Use clear headings and structure
• Test with one file before bulk upload

Web Crawling

• Start with single URL to test
• Verify pages load without JavaScript
• Respect robots.txt and rate limits
• Select only relevant pages

Monitoring

• Check status after uploads/crawls
• Retry failed documents promptly
• Review chunk counts for expected values
• Test RAG retrieval periodically

Related Documentation

• Upload Documents - File upload guide
• Web Crawling - URL import guide
• Document Processing - Processing pipeline
• RAG Integration - Configure retrieval

Still having issues? Open the Knowledge Base to check your document statuses, or contact support at [email protected].