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].