Skip to content

Troubleshooting

Jump to bottom
Jeremy Vyska edited this page Oct 30, 2025 · 3 revisions

Troubleshooting Guide

Comprehensive troubleshooting guide for resolving common issues with the BC Knowledge Base MCP Server, from installation problems to advanced configuration challenges.

🚨 Quick Issue Resolution

Most Common Issues

  1. MCP Server Not Starting - Server fails to initialize
  2. Knowledge Not Loading - Empty or missing knowledge base
  3. Tools Not Available - MCP tools not accessible
  4. Performance Issues - Slow response times
  5. Configuration Problems - Invalid or missing configuration
  6. Version Compatibility - BC version conflicts

Emergency Diagnostics

# Quick health check
bc-mcp --health-check

# Detailed diagnostics
bc-mcp --diagnose --verbose --output diagnostics.log

# Reset to defaults
bc-mcp --reset-config --backup-current

🔧 Installation & Setup Issues

MCP Server Not Starting

Symptoms

  • Server fails to start with error messages
  • Connection refused when accessing MCP tools
  • Process exits immediately after launch

Common Causes and Solutions

1. Node.js Version Incompatibility

# Check Node.js version
node --version

# Required: Node.js 18+ for MCP protocol support
# Solution: Upgrade Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

2. Missing Dependencies

# Check for missing dependencies
npm list --depth=0

# Install missing dependencies
npm install

# Force reinstall if corrupted
npm ci

3. Port Already in Use

# Check what's using the port
netstat -tulpn | grep :3000

# Kill process using the port
kill $(lsof -t -i:3000)

# Use alternative port
bc-mcp --port 3001

4. Permissions Issues

# Check file permissions
ls -la ~/.bckb/

# Fix permissions
chmod -R 755 ~/.bckb/
chown -R $USER:$USER ~/.bckb/

Advanced Diagnostics

# Enable debug logging
export BCKB_LOG_LEVEL=debug
export NODE_OPTIONS="--trace-warnings"

# Start with full diagnostics
bc-mcp --debug --trace-startup --log-file startup.log

# Check system resources
free -h
df -h
ps aux | grep node

Knowledge Not Loading

Symptoms

  • Empty knowledge base responses
  • "No topics found" errors
  • Missing domain knowledge

Common Causes and Solutions

1. Git Submodule Not Initialized

# Check submodule status
git submodule status

# Initialize submodules
git submodule update --init --recursive

# Verify knowledge content exists
ls -la embedded-knowledge/domains/

2. Knowledge Path Configuration

# Check knowledge path
bc-mcp --show-config | grep knowledge_path

# Reset to default path
bc-mcp --reset-knowledge-path

# Manually set knowledge path
export BCKB_KNOWLEDGE_PATH="/path/to/bc-knowledgebase"

3. Corrupted Knowledge Index

# Rebuild knowledge index
bc-mcp --rebuild-index

# Verify index integrity
bc-mcp --validate-index

# Clear and rebuild cache
bc-mcp --clear-cache --rebuild-index

4. Layer Configuration Issues

# Check layer configuration in .bckb/config.yaml
layers:
  embedded:
    enabled: true
    path: "./embedded-knowledge"
  company:
    enabled: false  # May be blocking knowledge loading
  project:
    enabled: true
    path: "./bckb-overrides"

Tools Not Available

Symptoms

  • MCP tools return "not found" errors
  • Tools list is empty
  • Specific tools missing from available set

Common Causes and Solutions

1. MCP Protocol Version Mismatch

# Check MCP protocol version
bc-mcp --version --protocol

# Update MCP dependencies
npm update @modelcontextprotocol/sdk

# Verify protocol compatibility
bc-mcp --check-protocol-compatibility

2. Tool Registration Issues

// Check tool registration in logs
export BCKB_LOG_LEVEL=debug

// Look for tool registration messages
bc-mcp 2>&1 | grep "Registering tool"

// Manually verify tool availability
bc-mcp --list-tools

3. Configuration Filtering

# Check if tools are disabled in config
tools:
  enabled:
    - "find_bc_topics"
    - "get_topic_content"
    # - "mcp_bckb_analyze_code_patterns"  # Commented out = disabled
  
  filters:
    by_domain: ["performance", "security"]  # May be too restrictive
    by_difficulty: ["intermediate", "advanced"]

⚡ Performance Issues

Slow Response Times

Symptoms

  • Knowledge queries take >5 seconds
  • Tool responses timeout
  • System becomes unresponsive

Diagnostics

# Monitor system resources
htop
iotop -ao

# Profile MCP server performance
bc-mcp --profile --output performance.json

# Check memory usage
bc-mcp --memory-usage --interval 5

# Monitor disk I/O
iostat -x 1

Optimization Solutions

1. Knowledge Index Optimization

# Rebuild optimized index
bc-mcp --rebuild-index --optimize

# Enable index caching
bc-mcp --config set cache.index.enabled=true
bc-mcp --config set cache.index.size=100MB

# Preload frequently used knowledge
bc-mcp --preload-domains "performance,security,api-design"

2. Memory Management

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Enable garbage collection optimization
export NODE_OPTIONS="--gc-strategy=adaptive"

# Monitor memory leaks
bc-mcp --memory-leak-detection --interval 60

3. Concurrent Request Handling

# Optimize server configuration in .bckb/config.yaml
server:
  max_concurrent_requests: 10
  request_timeout: 30s
  keep_alive_timeout: 60s
  
performance:
  enable_request_pooling: true
  cache_knowledge_queries: true
  preload_common_topics: true

High Memory Usage

Symptoms

  • Memory usage >1GB for basic operations
  • Out of memory errors
  • System swapping heavily

Solutions

# Enable memory optimization
bc-mcp --config set performance.memory_optimization=true

# Limit concurrent operations
bc-mcp --config set performance.max_concurrent_operations=5

# Enable lazy loading
bc-mcp --config set knowledge.lazy_loading=true

# Clear memory caches periodically
bc-mcp --schedule-memory-cleanup --interval 300

🔧 Configuration Problems

Invalid Configuration Files

Symptoms

  • "Configuration error" messages
  • Server fails to start with config errors
  • Tools behave unexpectedly

Common Issues

1. YAML Syntax Errors

# Validate YAML syntax
yamllint .bckb/config.yaml

# Check for common issues
bc-mcp --validate-config --verbose

# Use JSON schema validation
bc-mcp --validate-config --schema

2. Missing Required Configuration

# Minimal required configuration
version: "1.0"
server:
  port: 3000
  host: "localhost"

knowledge:
  embedded_path: "./embedded-knowledge"
  
layers:
  embedded:
    enabled: true

3. Environment Variable Conflicts

# Check environment variables
env | grep BCKB

# Clear conflicting variables
unset BCKB_CONFIG_OVERRIDE
unset BCKB_LEGACY_MODE

# Set required variables
export BCKB_CONFIG_PATH="$HOME/.bckb/config.yaml"

Layer Configuration Issues

💡 Configuration Issues?

The Chris Config specialist can diagnose configuration problems specific to your setup. Ask about:

  • "Why isn't my configuration file being discovered?"
  • "How do user and project configs merge in v1.5.3+?"
  • "Why are my layer priorities conflicting?"
  • "How do I troubleshoot Git layer authentication?"

Layer Override Problems

# Common layer configuration issues
layers:
  embedded:
    enabled: true
    priority: 100
    
  company:
    enabled: true
    priority: 50    # Should be higher than project
    path: "/invalid/path"  # Path doesn't exist
    
  project:
    enabled: true
    priority: 80    # Priority conflict with company
    path: "./bckb-overrides"

Solutions

# Validate layer configuration
bc-mcp --validate-layers

# Test layer resolution
bc-mcp --test-layer-resolution --topic "performance-optimization"

# Reset layer configuration
bc-mcp --reset-layers --keep-project-overrides

🔄 Version Compatibility Issues

BC Version Detection Problems

Symptoms

  • Wrong BC version detected
  • Version-specific knowledge not loading
  • Compatibility warnings for valid setups

Solutions

# Manually set BC version
export BCKB_BC_VERSION="23.1"

# Verify version detection
bc-mcp --detect-bc-version --verbose

# Force version override
bc-mcp --config set bc_version.override="24.0"
bc-mcp --config set bc_version.auto_detect=false

Knowledge Version Conflicts

Symptoms

  • Knowledge topics show version conflicts
  • Features unavailable in current BC version
  • Outdated recommendations

Resolution

# Update knowledge base
bc-mcp --update-knowledge --force

# Filter by BC version
bc-mcp --config set knowledge.version_filter="22+"

# Validate version compatibility
bc-mcp --validate-version-compatibility --bc-version "23.1"

🔍 Advanced Troubleshooting

Debug Mode and Logging

Enable Comprehensive Logging

# Set maximum debug level
export BCKB_LOG_LEVEL=trace
export BCKB_LOG_FILE="/tmp/bckb-debug.log"

# Enable component-specific logging
export BCKB_LOG_COMPONENTS="knowledge,layers,tools,server"

# Start with debugging
bc-mcp --debug --trace-all --log-to-console

Log Analysis

# Search for errors
grep -i error /tmp/bckb-debug.log

# Monitor real-time logs
tail -f /tmp/bckb-debug.log | grep -E "(ERROR|WARN|FAIL)"

# Analyze performance logs
grep "performance" /tmp/bckb-debug.log | awk '{print $1, $2, $(NF-1), $NF}'

Network and Connectivity Issues

MCP Connection Problems

# Test MCP protocol connectivity
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list", "id": 1}'

# Check firewall rules
sudo ufw status
iptables -L

# Test with different ports
bc-mcp --port 8080 --test-connectivity

Proxy and SSL Issues

# Configure proxy settings
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# Disable SSL verification (development only)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Use custom CA certificates
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

Knowledge Base Corruption

Symptoms

  • Inconsistent search results
  • Missing or duplicate topics
  • Index rebuilding fails

Recovery Steps

# 1. Backup current state
bc-mcp --backup-knowledge --output backup-$(date +%Y%m%d).tar.gz

# 2. Validate knowledge integrity
bc-mcp --validate-knowledge --comprehensive

# 3. Reset to clean state
bc-mcp --reset-knowledge --keep-overrides

# 4. Rebuild from source
git submodule update --remote --merge
bc-mcp --rebuild-index --force

# 5. Verify recovery
bc-mcp --test-knowledge-base --comprehensive

🛠️ Tool-Specific Issues

find_bc_topics Tool Problems

Common Issues

// Tool returns empty results
{
  "error": "No topics found matching criteria",
  "query": "performance optimization",
  "filters": {...}
}

// Debug search parameters
bc-mcp debug-tool find_bc_topics \
  --query "performance" \
  --tags "sift,optimization" \
  --bc-version "23+" \
  --verbose

Solutions

# Rebuild search index
bc-mcp --rebuild-search-index

# Verify topic metadata
bc-mcp --validate-topic-metadata

# Test with minimal filters
bc-mcp test-tool find_bc_topics --query "performance" --no-filters

get_topic_content Tool Issues

Access Denied Errors

# Check topic permissions
bc-mcp --check-topic-access "sift-technology-fundamentals"

# Verify layer access
bc-mcp --debug-layer-access --topic "performance-optimization"

# Reset topic cache
bc-mcp --clear-topic-cache

Methodology Tool Problems

Methodology Not Starting

// Common error pattern
{
  "error": "Methodology prerequisites not met",
  "methodology": "performance-optimization",
  "missing_prerequisites": ["bc_version", "environment_access"]
}

Solutions

# Validate methodology requirements
bc-mcp --validate-methodology-requirements "performance-optimization"

# Override prerequisites (development only)
bc-mcp --config set methodology.skip_prerequisites=true

# Test methodology in dry-run mode
bc-mcp test-methodology "performance-optimization" --dry-run

📊 Monitoring and Health Checks

Health Check Script

#!/bin/bash
# health-check.sh

echo "=== BC Knowledge Base MCP Server Health Check ==="

# 1. Server connectivity
echo "Testing server connectivity..."
if curl -s http://localhost:3000/health > /dev/null; then
    echo "✅ Server responding"
else
    echo "❌ Server not responding"
    exit 1
fi

# 2. Knowledge base accessibility
echo "Testing knowledge base..."
if bc-mcp test-tool find_bc_topics --query "test" --timeout 5 > /dev/null; then
    echo "✅ Knowledge base accessible"
else
    echo "❌ Knowledge base issues"
fi

# 3. Memory usage
echo "Checking memory usage..."
MEMORY_MB=$(ps -o rss= -p $(pgrep -f bc-mcp) | awk '{sum+=$1} END {print sum/1024}')
if [ "${MEMORY_MB%.*}" -lt 500 ]; then
    echo "✅ Memory usage normal (${MEMORY_MB}MB)"
else
    echo "⚠️ High memory usage (${MEMORY_MB}MB)"
fi

# 4. Response time
echo "Testing response time..."
START_TIME=$(date +%s%N)
bc-mcp test-tool find_bc_topics --query "performance" > /dev/null
END_TIME=$(date +%s%N)
RESPONSE_TIME=$(( (END_TIME - START_TIME) / 1000000 ))

if [ $RESPONSE_TIME -lt 2000 ]; then
    echo "✅ Response time good (${RESPONSE_TIME}ms)"
else
    echo "⚠️ Slow response time (${RESPONSE_TIME}ms)"
fi

echo "=== Health check complete ==="

Automated Monitoring

# monitoring-config.yaml
monitoring:
  health_checks:
    interval: "60s"
    timeout: "10s"
    
  metrics:
    - name: "response_time"
      threshold: "2000ms"
      action: "alert"
      
    - name: "memory_usage"
      threshold: "500MB"
      action: "log_warning"
      
    - name: "error_rate"
      threshold: "5%"
      action: "alert"
      
  alerts:
    email: "devops@company.com"
    slack: "#bc-alerts"
    webhook: "https://monitoring.company.com/webhook"

🆘 Getting Help

Community Support

Professional Support

  • Enterprise Support: Contact your BC partner or Microsoft support
  • Consulting Services: Available for complex implementations
  • Training Programs: Hands-on workshops for teams

Information to Include in Support Requests

# Generate support bundle
bc-mcp --generate-support-bundle --output support-bundle.zip

# Include in your request:
# 1. Support bundle (above)
# 2. BC version and environment details
# 3. Steps to reproduce the issue
# 4. Expected vs actual behavior
# 5. Any error messages or logs

Self-Help Resources

# Built-in help system
bc-mcp --help
bc-mcp help <command>

# Interactive troubleshooting
bc-mcp --interactive-troubleshoot

# Documentation search
bc-mcp --search-docs "keyword"

🔗 Related Documentation

Still having issues? Check our FAQ or reach out to the community for help.

Clone this wiki locally