Common Issues Guide

This guide covers the most frequently encountered issues when using QDrant Loader, along with step-by-step solutions and prevention strategies. Whether you're experiencing installation problems, data loading issues, or configuration difficulties, this guide provides practical solutions.

🎯 Quick Issue Identification

Symptom Checker

❌ Installation fails → See [Installation Issues](#installation-issues)
❌ Can't connect to QDrant → See [Connection Problems](./connection-problems.html)
❌ Data not loading → See [Data Loading Issues](#data-loading-issues)
❌ Configuration errors → See [Configuration Issues](#configuration-issues)
❌ MCP server not working → See [MCP Server Issues](#mcp-server-issues)
❌ Slow performance → See [Performance Issues](./performance-issues.html)

🔧 Installation Issues

Issue: pip install fails

Symptoms:

  • pip install qdrant-loader fails with dependency errors
  • Package not found errors
  • Permission denied errors

Solutions:

# Solution 1: Update pip and try again
pip install --upgrade pip
pip install qdrant-loader

# Solution 2: Use virtual environment
python -m venv qdrant-env
source qdrant-env/bin/activate  # On Windows: qdrant-env\Scripts\activate
pip install qdrant-loader

# Solution 3: Install with user flag
pip install --user qdrant-loader

# Solution 4: Force reinstall
pip install --force-reinstall qdrant-loader

Prevention:

  • Always use virtual environments
  • Keep pip updated
  • Check Python version compatibility (3.8+)

Issue: Command not found after installation

Symptoms:

  • qdrant-loader: command not found
  • Package installed but CLI not available

Solutions:

# Check if package is installed
pip list | grep qdrant-loader

# Find installation path
python -c "import qdrant_loader; print(qdrant_loader.__file__)"

# Add to PATH (if needed)
export PATH="$HOME/.local/bin:$PATH"

# Or use python -m
python -m qdrant_loader --help

Issue: Import errors

Symptoms:

  • ModuleNotFoundError: No module named 'qdrant_loader'
  • Import errors for dependencies

Solutions:

# Check Python environment
which python
python --version

# Reinstall with dependencies
pip install --upgrade qdrant-loader[all]

# Check for conflicting packages
pip check

# Clean install
pip uninstall qdrant-loader
pip install qdrant-loader

📊 Data Loading Issues

Issue: No data loaded from source

Symptoms:

  • Ingest command completes but no vectors in collection
  • "0 documents processed" message
  • Empty search results through MCP server

Diagnostic Steps:

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

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

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

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

Common Causes & Solutions:

  1. Incorrect file patterns:
# Problem: Too restrictive patterns in project configuration
projects:
  my-project:
    sources:
      localfile:
        my-docs:
          include_paths:
            - "*.md"  # Only markdown files

# Solution: Broader patterns
projects:
  my-project:
    sources:
      localfile:
        my-docs:
          include_paths:
            - "*.md"
            - "*.txt"
            - "*.rst"
            - "docs/**/*"
  1. Authentication issues:
# Check credentials
echo $QDRANT_API_KEY
echo $LLM_API_KEY
echo $OPENAI_API_KEY  # Legacy support
echo $CONFLUENCE_TOKEN
echo $JIRA_TOKEN

# Test QDrant connection
curl -H "api-key: $QDRANT_API_KEY" "$QDRANT_URL/health"

# Test LLM API (new unified approach)
curl -H "Authorization: Bearer $LLM_API_KEY" "https://api.openai.com/v1/models"

# Test legacy OpenAI API (still supported)
curl -H "Authorization: Bearer $OPENAI_API_KEY" "https://api.openai.com/v1/models"
  1. Path issues:
# Check if path exists and is accessible
ls -la /path/to/documents
find /path/to/documents -name "*.md" | head -5

# Use absolute paths in configuration
projects:
  my-project:
    sources:
      localfile:
        my-docs:
          base_url: "file:///absolute/path/to/docs"

Issue: Partial data loading

Symptoms:

  • Some files processed, others skipped
  • Inconsistent loading results
  • Warning messages about skipped files

Solutions:

# Check file permissions
find ./docs -name "*.md" ! -readable

# Check file encoding
file -i ./docs/*.md

# Force reinitialization and reload
qdrant-loader init --workspace . --force
qdrant-loader ingest --workspace .

# Check exclude patterns in configuration
qdrant-loader config --workspace . | grep -A 5 exclude_paths

Issue: Duplicate content

Symptoms:

  • Same content appears multiple times in search
  • Higher than expected vector count
  • Multiple sources pointing to same content

Solutions:

# Check for overlapping sources in configuration
qdrant-loader config --workspace .

# Review project configuration for duplicate sources
qdrant-loader config --workspace .

# Reinitialize collection to clean duplicates
qdrant-loader init --workspace . --force
qdrant-loader ingest --workspace .

⚙️ Configuration Issues

Issue: Configuration validation fails

Symptoms:

  • qdrant-loader config shows validation errors
  • YAML parsing errors
  • Missing required fields

Solutions:

# Check YAML syntax
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

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

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

# Validate specific project
qdrant-loader config --workspace . --project-id my-project

Common Configuration Problems:

  1. YAML indentation:
# Wrong indentation
global:
qdrant: url: "http://localhost:6333"

# Correct indentation
global:
  qdrant:
    url: "http://localhost:6333"
  1. Missing environment variables:
# Check required variables
env | grep -E "(QDRANT|OPENAI|CONFLUENCE|JIRA)"

# Set missing variables
export QDRANT_API_KEY="your-key-here"
export LLM_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"  # Legacy support
  1. Invalid URLs:
# Ensure URLs are complete and accessible
global:
  qdrant:
    url: "https://your-qdrant-instance.com"  # Include protocol

Issue: Environment variables not loaded

Symptoms:

  • Configuration uses literal ${VAR_NAME} instead of values
  • Authentication failures
  • Connection errors

Solutions:

# Check environment variables
echo $QDRANT_API_KEY
echo $LLM_API_KEY
echo $OPENAI_API_KEY  # Legacy support

# Load from .env file
export $(cat .env | xargs)

# Check if .env file exists in workspace
ls -la .env

# Verify configuration loads environment variables
qdrant-loader config --workspace .

Issue: LLM Configuration Migration (v0.7.1+)

Symptoms:

  • Deprecation warnings about global.embedding.*
  • Configuration validation errors
  • "Legacy configuration fields detected" warnings

Solutions:

# Check current configuration for legacy fields
qdrant-loader config --workspace . | grep -E "(embedding|openai):"

# Update configuration to new LLM syntax
# OLD (deprecated):
# global:
#   embedding:
#     api_key: "${OPENAI_API_KEY}"
#     model: "text-embedding-3-small"

# NEW (recommended):
# global:
#   llm:
#     provider: "openai"
#     base_url: "https://api.openai.com/v1"
#     api_key: "${LLM_API_KEY}"
#     models:
#       embeddings: "text-embedding-3-small"
#       chat: "gpt-4o-mini"
#     embeddings:
#       vector_size: 1536

# Validate updated configuration
qdrant-loader config --workspace .

Migration Checklist:

  • [ ] Replace global.embedding.* with global.llm.*
  • [ ] Add provider field (openai, azure_openai, ollama)
  • [ ] Add base_url field for API endpoint
  • [ ] Update models structure (embeddings, chat)
  • [ ] Add embeddings.vector_size field
  • [ ] Update environment variables to use LLM_API_KEY
  • [ ] Test configuration with qdrant-loader config --workspace .

Issue: Project configuration errors

Symptoms:

  • Projects not found or recognized
  • Invalid project structure
  • Missing required project fields

Solutions:

# List all configured projects
qdrant-loader config --workspace .

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

# Validate specific project
qdrant-loader config --workspace . --project-id my-project

# Check project configuration structure
qdrant-loader config --workspace . | grep -A 20 projects

🔌 MCP Server Issues

Issue: MCP server won't start

Symptoms:

  • Server fails to start
  • Import errors when starting MCP server
  • Permission denied errors

Solutions:

# Check if MCP server package is installed
pip list | grep qdrant-loader-mcp-server

# Install MCP server package
pip install qdrant-loader-mcp-server

# Start MCP server with debug logging
MCP_LOG_LEVEL=DEBUG mcp-qdrant-loader

# Check environment variables for MCP server
env | grep MCP

Issue: AI tools can't connect to MCP server

Symptoms:

  • Connection refused errors in AI tools
  • MCP server running but not accessible
  • Configuration issues in AI tools

Solutions:

# Check MCP server configuration in AI tool
# For Cursor, check: ~/.cursor/mcp_settings.json

# Verify MCP server is running
ps aux | grep mcp-qdrant-loader

# Test MCP server manually
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | mcp-qdrant-loader

# Check MCP server logs
tail -f ~/.qdrant-loader/logs/mcp-server.log

Issue: Search not working through MCP

Symptoms:

  • MCP server connected but search fails
  • Empty results through AI tools
  • MCP tools not available

Solutions:

# Verify workspace configuration
qdrant-loader config --workspace .

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

# Ensure data is loaded
qdrant-loader ingest --workspace .

# Restart MCP server with proper workspace
cd /path/to/workspace
mcp-qdrant-loader

🚨 Emergency Procedures

Complete System Reset

If you're experiencing multiple issues and need a fresh start:

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

# 2. Clean installation
pip uninstall qdrant-loader qdrant-loader-mcp-server
pip install qdrant-loader qdrant-loader-mcp-server

# 3. Validate configuration
qdrant-loader config --workspace .

# 4. Test basic functionality
qdrant-loader config --workspace .
qdrant-loader config --workspace .

# 5. Reinitialize and reload data
qdrant-loader init --workspace . --force
qdrant-loader ingest --workspace .

Data Recovery

If you've lost data or corrupted your collection:

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

# Reinitialize collection
qdrant-loader init --workspace . --force

# Reload all data from sources
qdrant-loader ingest --workspace .

# Verify data is loaded
qdrant-loader config --workspace .

📞 Getting Help

Before Asking for Help

  1. Check logs with debug mode:
qdrant-loader ingest --workspace . --log-level DEBUG
  1. Gather system information:
qdrant-loader --version
python --version
pip list | grep qdrant
uname -a
  1. Test minimal example:
# Create test workspace
mkdir test-workspace && cd test-workspace

# Create minimal configuration
cat > config.yaml << EOF
global:
  qdrant:
    url: "${QDRANT_URL}"
    api_key: "${QDRANT_API_KEY}"
  llm:
    provider: "openai"
    base_url: "https://api.openai.com/v1"
    api_key: "${LLM_API_KEY}"
    models:
      embeddings: "text-embedding-3-small"
      chat: "gpt-4o-mini"
    embeddings:
      vector_size: 1536

projects:
  test-project:
    display_name: "Test Project"
    collection_name: "test_collection"
    sources:
      localfile:
        test-docs:
          base_url: "file://./test-docs"
          include_paths: ["*.md"]
EOF

# Create test data
mkdir test-docs
echo "# Test Document" > test-docs/test.md

# Test loading
qdrant-loader init --workspace .
qdrant-loader ingest --workspace .

Support Channels

Issue Report Template

## Issue Description

Brief description of the problem

## Environment

- OS: [e.g., Ubuntu 22.04]
- Python: [e.g., 3.11.5]
- QDrant Loader: [e.g., 1.2.3]
- QDrant: [e.g., 1.7.0]

## Steps to Reproduce

1. Step one
2. Step two
3. Step three

## Expected Behavior

What you expected to happen

## Actual Behavior

What actually happened

## Configuration

```yaml
[Paste relevant configuration (sanitized)]

Logs

[Paste relevant logs here]

Commands Used

# List the exact commands you ran
qdrant-loader config --workspace .
qdrant-loader config --workspace .

```text

🔗 Related Documentation

Most common issues resolved! 🎉

This guide covers the majority of issues users encounter. For specific error messages, check the Error Messages Reference, and for performance-related problems, see the Performance Issues Guide.