Troubleshooting Guide

Welcome to the QDrant Loader troubleshooting guide! This section provides comprehensive solutions for common issues, performance problems, and error messages you might encounter. Whether you're a new user or an experienced developer, these guides will help you quickly identify and resolve problems.

🎯 Quick Problem Identification

Symptom Checker

Use this quick reference to identify your issue and jump to the right solution:

❌ Installation fails                    → [Common Issues](./common-issues.md#installation-issues)
🔌 Can't connect to QDrant              → [Connection Problems](./connection-problems.md#qdrant-connection-issues)
🔑 Authentication errors                → [Connection Problems](./connection-problems.md#authentication-problems)
📊 Data won't load                      → [Common Issues](./common-issues.md#data-loading-issues)
🔍 Search returns no results            → [Common Issues](./common-issues.md#search-issues)
🐌 Everything is slow                   → [Performance Issues](./performance-issues.md)
💾 High memory usage                    → [Performance Issues](./performance-issues.md#memory-issues)
🌐 Network timeouts                     → [Connection Problems](./connection-problems.md#network-issues)
🛡️ Firewall blocking                   → [Connection Problems](./connection-problems.md#firewall-problems)
📁 File permission errors               → [Error Messages](./error-messages-reference.md#file-system-errors)
⚙️ Configuration problems               → [Error Messages](./error-messages-reference.md#configuration-errors)

Error Message Lookup

Got a specific error message? Look it up directly:

# Search for your error message in documentation
grep -r "your error message" docs/users/troubleshooting/

# Or check the comprehensive error reference
# See: Error Messages Reference → [specific error category]

📚 Troubleshooting Guides

🔧 Common Issues

Start here for most problems! Covers the most frequently encountered issues with step-by-step solutions.

What's covered:

  • Installation and setup problems
  • Data loading issues
  • Search and query problems
  • Configuration errors
  • Quick fixes and workarounds

Best for: New users, general problems, first-time setup issues

🚀 Performance Issues

Comprehensive guide for diagnosing and resolving performance problems.

What's covered:

  • Slow data loading optimization
  • Search performance tuning
  • Memory usage optimization
  • CPU and resource management
  • Network performance issues
  • Advanced optimization strategies

Best for: Large datasets, production environments, performance optimization

🔌 Connection Problems

Detailed solutions for connectivity and network-related issues.

What's covered:

  • QDrant instance connectivity
  • API authentication problems
  • Network configuration issues
  • Firewall and proxy problems
  • SSL/TLS certificate issues
  • Advanced connection troubleshooting

Best for: Network issues, authentication problems, enterprise environments

📖 Error Messages Reference

Comprehensive reference for all error messages with exact solutions.

What's covered:

  • Complete error message catalog
  • Detailed explanations and causes
  • Step-by-step solutions
  • Error codes and exit codes
  • Prevention strategies

Best for: Specific error messages, debugging, development

🚨 Emergency Quick Fixes

When Everything Fails

# 1. Check basic configuration
qdrant-loader --workspace . config

# 2. Validate project configuration
qdrant-loader project --workspace . validate

# 3. Check system resources
free -h && df -h && ps aux | grep qdrant-loader

# 4. Reinitialize collection (WARNING: This will delete existing data)
qdrant-loader --workspace . init --force

Critical System Recovery

# Test network connectivity
ping 8.8.8.8 && curl -v https://api.openai.com/v1/models

# Test QDrant connectivity
curl -v "$QDRANT_URL/health"

# Check environment variables
env | grep -E "(QDRANT|OPENAI|CONFLUENCE|JIRA)"

# Verify workspace structure
ls -la config.yaml .env

🔍 Diagnostic Tools

Built-in Diagnostics

# Check current configuration
qdrant-loader --workspace . config

# List all projects
qdrant-loader project --workspace . list

# Check project status
qdrant-loader project --workspace . status

# Validate configuration
qdrant-loader project --workspace . validate

# Test with debug logging
qdrant-loader --workspace . --log-level DEBUG config

Manual Diagnostics

# Check system resources
htop
iostat -x 1
free -h
df -h

# Network diagnostics
ping your-qdrant-instance.com
traceroute your-qdrant-instance.com
nslookup your-qdrant-instance.com

# Service status
systemctl status qdrant  # If using systemd
docker ps | grep qdrant  # If using Docker

📊 Problem Categories

By Frequency (Most Common First)

  1. Configuration Issues (40%)
  2. Environment variables not set
  3. Invalid YAML syntax
  4. Missing required fields

  5. → Error Messages Reference

  6. Connection Problems (25%)

  7. QDrant instance not accessible
  8. Authentication failures
  9. Network timeouts

  10. → Connection Problems

  11. Data Loading Issues (20%)

  12. No documents found
  13. File processing errors
  14. Memory limitations

  15. → Common Issues

  16. Performance Problems (10%)

  17. Slow loading or search
  18. High resource usage
  19. Timeout errors

  20. → Performance Issues

  21. Other Issues (5%)

  22. File permissions
  23. SSL/TLS problems
  24. Specific error messages
  25. → Error Messages Reference

By User Type

New Users

  • Start with Common Issues
  • Focus on installation and basic setup
  • Use quick fixes and simple solutions

Developers

System Administrators

Enterprise Users

🛠️ Troubleshooting Methodology

Step-by-Step Approach

  1. Identify the Problem
  2. What exactly is failing?
  3. When did it start failing?

  4. What changed recently?

  5. Gather Information

  6. Check error messages
  7. Review logs

  8. Test basic connectivity

  9. Apply Solutions

  10. Start with simple fixes
  11. Test after each change

  12. Document what works

  13. Verify Resolution

  14. Test the original use case
  15. Monitor for recurrence
  16. Update documentation

Diagnostic Commands

# Basic configuration check
qdrant-loader --workspace . config

# Project validation
qdrant-loader project --workspace . validate

# Project status check
qdrant-loader project --workspace . status

# Debug mode for detailed logging
qdrant-loader --workspace . --log-level DEBUG ingest

📈 Monitoring and Prevention

Proactive Monitoring

# Regular configuration validation
qdrant-loader project --workspace . validate

# Check project status regularly
qdrant-loader project --workspace . status

# Monitor system resources
watch -n 30 'free -h && df -h'

Prevention Strategies

  1. Regular Health Checks

bash # Daily configuration validation script qdrant-loader project --workspace . validate >> daily-health.log 2>&1

  1. Configuration Validation

bash # Validate before deployment qdrant-loader project --workspace . validate

  1. System Monitoring

bash # Monitor system resources free -h && df -h && ps aux | grep qdrant-loader

  1. Backup Strategy

bash # Backup configuration files cp config.yaml config.yaml.backup cp .env .env.backup

🔗 Getting Additional Help

Community Resources

Professional Support

  • Enterprise Support: Contact your support representative
  • Consulting Services: Professional implementation assistance
  • Training: Workshops and training sessions

Before Asking for Help

  1. Check this troubleshooting guide - Most issues are covered here
  2. Search existing issues - Your problem might already be solved
  3. Gather diagnostic information:

bash # Collect configuration and status information qdrant-loader --workspace . config > diagnostics.txt qdrant-loader project --workspace . list >> diagnostics.txt qdrant-loader project --workspace . status >> diagnostics.txt qdrant-loader project --workspace . validate >> diagnostics.txt 2>&1

  1. Provide clear details:
  2. Exact error messages
  3. Steps to reproduce
  4. System information
  5. Configuration (sanitized)

📋 Troubleshooting Checklist

Pre-Troubleshooting Checklist

  • [ ] Read the error message carefully
  • [ ] Check if QDrant instance is running
  • [ ] Verify environment variables are set
  • [ ] Test basic network connectivity
  • [ ] Check available system resources
  • [ ] Review recent configuration changes

Post-Solution Checklist

  • [ ] Verify the issue is completely resolved
  • [ ] Test related functionality
  • [ ] Document the solution for future reference
  • [ ] Update monitoring if needed
  • [ ] Share solution with team if applicable

🎯 Quick Reference Cards

Connection Issues Quick Card

# Test QDrant connection
curl -v "$QDRANT_URL/health"

# Test OpenAI API
curl -H "Authorization: Bearer $OPENAI_API_KEY" "https://api.openai.com/v1/models"

# Check environment variables
env | grep -E "(QDRANT|OPENAI|CONFLUENCE|JIRA)"

# Test configuration
qdrant-loader --workspace . config

Performance Issues Quick Card

# Check system resources
free -h && df -h && top

# Monitor QDrant Loader process
ps aux | grep qdrant-loader

# Check project status
qdrant-loader project --workspace . status

# Use debug logging for performance analysis
qdrant-loader --workspace . --log-level DEBUG ingest --profile

Data Loading Quick Card

# Check source accessibility
ls -la /path/to/docs

# Validate configuration
qdrant-loader project --workspace . validate

# Check project configuration
qdrant-loader --workspace . config

# Load with verbose output
qdrant-loader --workspace . --log-level DEBUG ingest

Configuration Issues Quick Card

# Display current configuration
qdrant-loader --workspace . config

# Validate all projects
qdrant-loader project --workspace . validate

# List configured projects
qdrant-loader project --workspace . list

# Check specific project
qdrant-loader project --workspace . status --project-id PROJECT_ID

Need immediate help? Start with the Common Issues Guide for quick solutions to the most frequent problems.

Got a specific error? Jump directly to the Error Messages Reference for detailed explanations and solutions.

Performance problems? Check the Performance Issues Guide for optimization strategies.

Connection troubles? See the Connection Problems Guide for network and authentication solutions.

Back to Documentation
Generated from README.md