Troubleshooting Guide

Common issues and solutions when using Skill Seeker.

Installation Issues

Python Not Found

Error:

python3: command not found

Solutions:

  1. Check if Python is installed:

    which python3
python --version  # Try without the 3

  2. Install Python:

    • macOS: brew install python3
    • Linux: sudo apt install python3 python3-pip
    • Windows: Download from python.org, check “Add to PATH”

  3. Use python instead of python3:

    python cli/doc_scraper.py --help

Module Not Found

Error:

ModuleNotFoundError: No module named 'requests'
ModuleNotFoundError: No module named 'bs4'
ModuleNotFoundError: No module named 'mcp'

Solutions:

  1. Install dependencies:

    pip3 install requests beautifulsoup4
pip3 install -r mcp/requirements.txt  # For MCP

  2. Use —user flag if permission denied:

    pip3 install --user requests beautifulsoup4

  3. Check pip is working:

    pip3 --version

Permission Denied

Error:

Permission denied: '/usr/local/lib/python3.x/...'

Solutions:

  1. Use —user flag:

    pip3 install --user requests beautifulsoup4

  2. Use sudo (not recommended):

    sudo pip3 install requests beautifulsoup4

  3. Use virtual environment (best practice):

    python3 -m venv venv
source venv/bin/activate
pip install requests beautifulsoup4

Runtime Issues

File Not Found

Error:

FileNotFoundError: [Errno 2] No such file or directory: 'cli/doc_scraper.py'

Solutions:

  1. Check you’re in the Skill_Seekers directory:

    pwd
# Should show: .../Skill_Seekers

ls
# Should show: README.md, cli/, mcp/, configs/

  2. Change to the correct directory:

    cd ~/Projects/Skill_Seekers  # Adjust path

Config File Not Found

Error:

FileNotFoundError: configs/react.json

Solutions:

  1. Check config exists:

    ls configs/
# Should show: godot.json, react.json, vue.json, etc.

  2. Use full path:

    skill-seekers scrape --config $(pwd)/configs/react.json

  3. Create missing config:

    skill-seekers scrape --interactive

MCP Setup Issues

MCP Server Not Loading

Symptoms:

  • Tools don’t appear in Claude Code
  • “List all available configs” doesn’t work

Solutions:

  1. Check configuration file:

    cat ~/.config/claude-code/mcp.json

  2. Verify paths are ABSOLUTE (not placeholders):

    {
  "mcpServers": {
    "skill-seeker": {
      "args": [
        "/Users/yourname/Projects/Skill_Seekers/mcp/server.py"
      ]
    }
  }
}

    ❌ Bad: $REPO_PATH or /path/to/Skill_Seekers ✅ Good: /Users/john/Projects/Skill_Seekers

  3. Test server manually:

    cd ~/Projects/Skill_Seekers
python3 mcp/server.py
# Should start without errors (Ctrl+C to stop)

  4. Re-run setup script:

    ./setup_mcp.sh
# Select "y" for auto-configure

  5. RESTART Claude Code completely:

    • Quit (don’t just close window)
    • Reopen

Placeholder Paths in Config

Problem: Config has $REPO_PATH or /Users/username/ instead of real paths

Solution:

# Get your actual path
cd ~/Projects/Skill_Seekers
pwd
# Copy this path

# Edit config
nano ~/.config/claude-code/mcp.json

# Replace ALL instances of placeholders with your actual path
# Save (Ctrl+O, Enter, Ctrl+X)

# Restart Claude Code

Tools Appear But Don’t Work

Symptoms:

  • Tools listed but commands fail
  • “Error executing tool” messages

Solutions:

  1. Check working directory:

    {
  "cwd": "/FULL/PATH/TO/Skill_Seekers"
}

  2. Verify files exist:

    ls cli/doc_scraper.py
ls mcp/server.py

  3. Test CLI tools directly:

    skill-seekers scrape --help

Scraping Issues

Slow or Hanging

Solutions:

  1. Check network connection:

    ping google.com
curl -I https://docs.yoursite.com

  2. Use smaller max_pages for testing:

    skill-seekers scrape --config configs/test.json --max-pages 5

  3. Increase rate_limit in config:

    {
  "rate_limit": 1.0  // Increase from 0.5
}

No Content Extracted

Problem: Pages scraped but content is empty

Solutions:

  1. Check selector in config:

    # Test with browser dev tools
# Look for: article, main, div[role="main"], div.content

  2. Verify website is accessible:

    curl https://docs.example.com

  3. Try different selectors:

    {
  "selectors": {
    "main_content": "article"  // Try: main, div.content, etc.
  }
}

Rate Limiting / 429 Errors

Error:

HTTP Error 429: Too Many Requests

Solutions:

  1. Increase rate_limit:

    {
  "rate_limit": 2.0  // Wait 2 seconds between requests
}

  2. Reduce max_pages:

    {
  "max_pages": 50  // Scrape fewer pages
}

  3. Try again later:

    # Wait an hour and retry

Platform-Specific Issues

macOS

Issue: Can’t run ./setup_mcp.sh

Solution:

chmod +x setup_mcp.sh
./setup_mcp.sh

Issue: Homebrew not installed

Solution:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Linux

Issue: pip3 not found

Solution:

sudo apt update
sudo apt install python3-pip

Issue: Permission errors

Solution:

# Use --user flag
pip3 install --user requests beautifulsoup4

Windows (WSL)

Issue: Python not in PATH

Solution:

  1. Reinstall Python
  2. Check “Add Python to PATH”
  3. Or add manually to PATH

Issue: Line ending errors

Solution:

dos2unix setup_mcp.sh
./setup_mcp.sh

Verification Commands

Use these to check your setup:

# 1. Check Python
python3 --version  # Should be 3.10+

# 2. Check dependencies
pip3 list | grep requests
pip3 list | grep beautifulsoup4
pip3 list | grep mcp

# 3. Check files exist
ls cli/doc_scraper.py
ls mcp/server.py
ls configs/

# 4. Check MCP config
cat ~/.config/claude-code/mcp.json

# 5. Test scraper
skill-seekers scrape --help

# 6. Test MCP server
timeout 3 python3 mcp/server.py || echo "Server OK"

# 7. Check git repo
git status
git log --oneline -5

Getting Help

If none of these solutions work:

  1. Check existing issues: https://github.com/yusufkaraaslan/Skill_Seekers/issues

  2. Open a new issue with:

    • Your OS (macOS 13, Ubuntu 22.04, etc.)
    • Python version (python3 --version)
    • Full error message
    • What command you ran
    • Output of verification commands above

  3. Include this debug info:

    # System info
uname -a
python3 --version
pip3 --version

# Skill Seeker info
cd ~/Projects/Skill_Seekers  # Your path
pwd
git log --oneline -1
ls -la cli/ mcp/ configs/

# MCP config (if using MCP)
cat ~/.config/claude-code/mcp.json

Quick Fixes Checklist

  • In the Skill_Seekers directory? (pwd)
  • Python 3.10+ installed? (python3 --version)
  • Dependencies installed? (pip3 list | grep requests)
  • Config file exists? (ls configs/yourconfig.json)
  • Internet connection working? (ping google.com)
  • For MCP: Config uses absolute paths? (not $REPO_PATH)
  • For MCP: Claude Code restarted? (quit and reopen)

Still stuck? Open an issue: https://github.com/yusufkaraaslan/Skill_Seekers/issues/new

Next Steps