​

Knowledge Base Troubleshooting

​

Overview

This comprehensive troubleshooting guide helps diagnose and resolve common issues with knowledge base collections, content management, and agent integration. Use this systematic approach to identify problems and implement effective solutions.

​

Common Knowledge Base Issues

​

Collection Management Issues

​

Cannot Create Collection

Symptoms:

• Collection creation fails with error messages
• Form validation prevents submission
• Creation process appears to hang

Possible Causes:

1. Collection name already exists
2. Invalid characters in collection name
3. Missing required fields
4. Network connectivity issues
5. User permission restrictions

Diagnostic Steps:

1. Verify collection name is unique and follows naming conventions
2. Check all required fields are completed
3. Test internet connectivity
4. Verify user has collection creation permissions
5. Try different collection names

Solutions:

1. Name Issues: Use unique, descriptive names with English characters only
2. Validation: Complete all required fields with valid information
3. Connectivity: Ensure stable internet connection
4. Permissions: Contact administrator for proper access rights
5. Alternative Names: Try suggested names or variations

​

Collection Not Appearing in Lists

Symptoms:

• Created collection doesn’t show in collection list
• Collection missing from agent integration options
• Intermittent collection visibility

Possible Causes:

• Browser cache issues
• Collection creation incomplete
• Permission synchronization delays
• Database synchronization issues

Solutions:

1. Refresh Browser: Clear cache and refresh page
2. Wait for Sync: Allow time for database synchronization
3. Re-login: Log out and back in to refresh permissions
4. Contact Support: If issue persists, contact technical support

​

Content Upload Issues

​

File Upload Failures

Symptoms:

• Files fail to upload with error messages
• Upload progress stops or freezes
• Error messages about file format or size

Common Causes:

1. File size exceeds limits (30,000 characters for free plan)
2. Unsupported file format
3. Network connectivity problems
4. Corrupted or protected files
5. Browser compatibility issues

Diagnostic Steps:

1. Check file size and format requirements
2. Test network connection stability
3. Try different files to isolate the issue
4. Attempt upload from different browser
5. Verify file isn’t corrupted or password-protected

Solutions:

1. Size Issues:
   • Compress large files or split into smaller documents
   • Upgrade plan for higher limits
   • Remove unnecessary content from documents
2. Format Issues:
   • Convert to supported formats (PDF, DOC, DOCX, TXT)
   • Ensure files contain actual text, not just images
   • Remove password protection from files
3. Network Issues:
   • Check internet connection stability
   • Try upload during off-peak hours
   • Use wired connection instead of WiFi
4. Browser Issues:
   • Try different web browser
   • Clear browser cache and cookies
   • Disable browser extensions temporarily

​

URL Crawling Problems

Symptoms:

• URLs fail to crawl with error messages
• Partial content extraction
• No content extracted from valid URLs

Common Causes:

1. URLs not publicly accessible
2. Content behind login or paywall
3. Heavy dynamic content (JavaScript-rendered)
4. Robot.txt restrictions
5. Network or server issues

Solutions:

1. Accessibility: Ensure URLs are publicly accessible without login
2. Content Type: Use pages with static text content
3. Format: Prefer documentation and help pages over dynamic content
4. Alternative Sources: Find alternative URLs with same information
5. Manual Entry: Copy content manually if URL crawling fails

​

Content Quality Issues

Symptoms:

• Extracted content is garbled or incomplete
• Missing important information
• Irrelevant or poor-quality content

Solutions:

1. Source Quality: Use well-formatted, high-quality source documents
2. Manual Review: Review and edit extracted content manually
3. Alternative Sources: Find better formatted versions of information
4. Content Curation: Remove low-quality or irrelevant content

​

Agent Integration Issues

​

Agents Can’t Access Collections

Symptoms:

• Agents provide generic responses instead of using knowledge
• Knowledge-based answers are missing or incorrect
• Agents appear unaware of collection content

Possible Causes:

1. Knowledge base capability not enabled for agent
2. Collections not connected to agent
3. Agent configuration not saved properly
4. Permission issues between agent and collections
5. Collection content indexing incomplete

Diagnostic Steps:

1. Check agent configuration for knowledge base capability
2. Verify collections are connected to agent
3. Confirm agent configuration is saved
4. Test agent responses with known collection content
5. Check collection content is properly indexed

Solutions:

1. Enable Capability: Turn on knowledge base capability in agent configuration
2. Connect Collections: Link relevant collections to agent in Collections tab
3. Save Configuration: Ensure all changes are properly saved
4. Wait for Processing: Allow time for collection indexing
5. Test Integration: Test agent with specific questions about collection content

​

Poor Knowledge Retrieval Quality

Symptoms:

• Agents find irrelevant information
• Important information is missed in searches
• Inconsistent knowledge access across conversations

Possible Causes:

1. Poor content organization within collections
2. Inadequate content context and metadata
3. Collection content conflicts or duplicates
4. Search algorithm limitations
5. Insufficient content coverage

Solutions:

1. Content Organization: Improve structure and categorization of content
2. Add Context: Include more context and relevant keywords
3. Remove Conflicts: Eliminate duplicate or conflicting information
4. Gap Analysis: Identify and fill information gaps
5. Quality Review: Regular audit of content quality and relevance

​

Performance Issues

​

Slow Content Processing

Symptoms:

• Long delays when adding content to collections
• Upload processes that appear to hang
• Slow response times when accessing collections

Possible Causes:

1. Large file sizes or large numbers of files
2. Complex document formats requiring intensive processing
3. High system load during peak usage times
4. Network bandwidth limitations
5. Server processing constraints

Solutions:

1. File Optimization: Use smaller, well-formatted files
2. Batch Processing: Upload content in smaller batches
3. Timing: Process content during off-peak hours
4. Format Choice: Use simpler document formats when possible
5. Patience: Allow adequate time for processing complex content

​

Search Performance Issues

Symptoms:

• Slow search results within collections
• Timeouts when searching large collections
• Inconsistent search response times

Solutions:

1. Collection Size: Consider splitting very large collections
2. Content Optimization: Remove unnecessary or redundant content
3. Index Maintenance: Allow time for search index updates
4. Query Optimization: Use more specific search terms
5. System Resources: Contact support if performance issues persist

​

Systematic Troubleshooting Process

​

Step 1: Problem Identification

Information to Gather:

• Specific symptoms and error messages
• When the problem started occurring
• Which components are affected (collections, content, agents)
• Recent changes or updates made
• Impact on business operations

​

Step 2: Initial Diagnosis

Areas to Check:

• System status and connectivity
• User permissions and access rights
• Recent configuration changes
• Content quality and format
• Agent integration settings

​

Step 3: Isolation Testing

Testing Approach:

• Test with minimal configuration
• Use known-good content or collections
• Test single components individually
• Isolate variables and dependencies
• Compare working vs. non-working scenarios

​

Step 4: Solution Implementation

Best Practices:

• Make one change at a time
• Test changes thoroughly before proceeding
• Document what works and what doesn’t
• Monitor impact of changes
• Keep backup of working configurations

​

Step 5: Verification and Monitoring

Follow-up Actions:

• Verify problem is resolved
• Monitor for recurring issues
• Test related functionality
• Document successful solutions
• Update procedures based on learnings

​

Content-Specific Troubleshooting

​

PDF Content Issues

​

Text Extraction Problems

Common Issues:

• Scanned PDFs (image-based) don’t extract text
• Complex layouts cause garbled extraction
• Password-protected PDFs can’t be processed

Solutions:

1. OCR Processing: Use OCR software for scanned documents
2. Format Conversion: Convert to simpler formats like Word or plain text
3. Manual Entry: Type or copy-paste content manually
4. Remove Protection: Remove password protection before upload

​

Document Structure Issues

Common Issues:

• Tables and charts don’t extract properly
• Headers and footers interfere with content
• Multi-column layouts cause confusion

Solutions:

1. Content Preparation: Clean up document formatting before upload
2. Manual Editing: Edit extracted content to fix structure issues
3. Alternative Formats: Use Word documents with simpler layouts
4. Section by Section: Break complex documents into smaller sections

​

Web Content Issues

​

Dynamic Content Problems

Common Issues:

• JavaScript-rendered content not extracted
• Content behind login screens inaccessible
• Constantly changing content creates inconsistencies

Solutions:

1. Static Alternatives: Find static versions of the same content
2. Documentation Pages: Use dedicated help or documentation pages
3. Manual Extraction: Copy content manually from dynamic pages
4. API Access: Use official APIs if available for content access

​

Access Restrictions

Common Issues:

• Content behind paywalls or membership restrictions
• Corporate intranets or private sites
• Geographic or legal access restrictions

Solutions:

1. Public Alternatives: Find publicly accessible versions
2. Official Documentation: Use official help and support pages
3. Content Creation: Create your own version of the information
4. Permission: Obtain proper permissions for restricted content

​

Advanced Troubleshooting

​

Data Integrity Issues

​

Content Corruption

Symptoms:

• Garbled or nonsensical text in collections
• Missing sections of content
• Formatting artifacts and strange characters

Diagnostic Steps:

1. Check original source material quality
2. Verify upload process completed successfully
3. Test with different file formats
4. Compare extracted content with original

Solutions:

1. Re-upload: Try uploading content again
2. Format Change: Convert to different file format
3. Manual Correction: Edit content manually to fix issues
4. Source Improvement: Use higher quality source materials

​

Synchronization Issues

Symptoms:

• Content appears in some places but not others
• Inconsistent content across different views
• Delays in content updates appearing

Solutions:

1. Wait for Sync: Allow time for system synchronization
2. Force Refresh: Clear cache and refresh browsers
3. Re-index: Trigger content re-indexing if available
4. Contact Support: Report persistent synchronization issues

​

Integration Complexity

​

Multi-Agent Conflicts

Symptoms:

• Different agents provide conflicting information
• Inconsistent responses across agents
• Some agents access content while others don’t

Solutions:

1. Configuration Review: Check each agent’s collection connections
2. Content Audit: Ensure consistent content across collections
3. Priority Setting: Establish clear information hierarchies
4. Standardization: Standardize agent configurations

​

Performance at Scale

Symptoms:

• System slowdown with large numbers of collections
• Timeout issues with extensive content libraries
• Memory or processing constraints

Solutions:

1. Architecture Review: Optimize system architecture for scale
2. Content Optimization: Streamline and optimize content libraries
3. Resource Scaling: Increase system resources as needed
4. Usage Patterns: Analyze and optimize usage patterns

​

Prevention Strategies

​

Regular Maintenance

​

Content Maintenance

Weekly Tasks:

• Review content quality and accuracy
• Check for broken links or outdated information
• Monitor agent performance with knowledge base
• Address any reported content issues

Monthly Tasks:

• Comprehensive content audit
• Performance analysis and optimization
• System capacity and usage review
• Update documentation and procedures

​

System Maintenance

Monitoring:

• Set up alerts for system issues
• Monitor performance metrics
• Track user feedback and issues
• Regular backup and recovery testing

​

Quality Assurance

​

Content Standards

• Establish clear content quality guidelines
• Implement review processes for new content
• Regular training for content contributors
• Feedback collection and improvement processes

​

Technical Standards

• Maintain consistent file formats and structures
• Establish naming conventions for collections
• Document standard procedures and troubleshooting steps
• Regular testing of critical functionality

​

Escalation Guidelines

​

When to Escalate

Internal Escalation:

• Multiple troubleshooting attempts failed
• System-wide issues affecting multiple users
• Performance degradation requiring technical intervention
• Data integrity or security concerns

External Support:

• Platform-specific issues requiring vendor support
• Integration problems with third-party systems
• Complex technical issues beyond internal capabilities
• Critical business impact requiring immediate resolution

​

Information to Provide

For Support Requests:

• Detailed problem description with specific symptoms
• Steps already taken to resolve the issue
• Error messages and system logs
• Impact assessment and urgency level
• Business context and requirements