skill-seekers-reference/docs/user-guide/06-troubleshooting.md

Troubleshooting Guide

Skill Seekers v3.1.0
Common issues and solutions

---

Quick Fixes

Issue	Quick Fix
command not found	export PATH="$HOME/.local/bin:$PATH"
ImportError	pip install -e .
Rate limit	Add --rate-limit 2.0
No content	Check selectors in config
Enhancement fails	Set ANTHROPIC_API_KEY
Out of memory	Use --streaming mode

---

Installation Issues

"command not found: skill-seekers"

Cause: pip bin directory not in PATH

Solution:

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Or reinstall with --user
pip install --user --force-reinstall skill-seekers

# Verify
which skill-seekers

---

"No module named 'skill_seekers'"

Cause: Package not installed or wrong Python environment

Solution:

# Install package
pip install skill-seekers

# For development
pip install -e .

# Verify
python -c "import skill_seekers; print(skill_seekers.__version__)"

---

"Permission denied"

Cause: Trying to install system-wide

Solution:

# Don't use sudo
# Instead:
pip install --user skill-seekers

# Or use virtual environment
python3 -m venv venv
source venv/bin/activate
pip install skill-seekers

---

Scraping Issues

"Rate limit exceeded"

Cause: Too many requests to server

Solution:

# Slow down
skill-seekers create <url> --rate-limit 2.0

# For GitHub
export GITHUB_TOKEN=ghp_...
skill-seekers github --repo owner/repo

---

"No content extracted"

Cause: Wrong CSS selectors

Solution:

# Find correct selectors
curl -s <url> | grep -i 'article\|main\|content'

# Create config with correct selectors
cat > configs/fix.json << 'EOF'
{
  "name": "my-site",
  "base_url": "https://example.com/",
  "selectors": {
    "main_content": "article"  # or "main", ".content", etc.
  }
}
EOF

skill-seekers create --config configs/fix.json

Common selectors:

Site Type	Selector
Docusaurus	article
ReadTheDocs	[role="main"]
GitBook	.book-body
MkDocs	.md-content

---

"Too many pages"

Cause: Site larger than max_pages setting

Solution:

# Estimate first
skill-seekers estimate configs/my-config.json

# Increase limit
skill-seekers create <url> --max-pages 1000

# Or limit in config
{
  "max_pages": 1000
}

---

"Connection timeout"

Cause: Slow server or network issues

Solution:

# Increase timeout
skill-seekers create <url> --timeout 60

# Or in config
{
  "timeout": 60
}

---

"SSL certificate error"

Cause: Certificate validation failure

Solution:

# Set environment variable (not recommended for production)
export PYTHONWARNINGS="ignore:Unverified HTTPS request"

# Or use requests settings in config
{
  "verify_ssl": false
}

---

Enhancement Issues

"Enhancement failed: No API key"

Cause: ANTHROPIC_API_KEY not set

Solution:

# Set API key
export ANTHROPIC_API_KEY=sk-ant-...

# Or use LOCAL mode
skill-seekers enhance output/my-skill/ --agent local

---

"Claude Code not found" (LOCAL mode)

Cause: Claude Code not installed

Solution:

# Install Claude Code
# See: https://claude.ai/code

# Or use API mode
export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers enhance output/my-skill/ --agent api

---

"Enhancement timeout"

Cause: Enhancement taking too long

Solution:

# Increase timeout
skill-seekers enhance output/my-skill/ --timeout 1200

# Use background mode
skill-seekers enhance output/my-skill/ --background
skill-seekers enhance-status output/my-skill/ --watch

---

"Workflow not found"

Cause: Typo or workflow doesn't exist

Solution:

# List available workflows
skill-seekers workflows list

# Check spelling
skill-seekers create <source> --enhance-workflow security-focus

---

Packaging Issues

"Package validation failed"

Cause: SKILL.md missing or malformed

Solution:

# Check structure
ls output/my-skill/

# Should contain:
# - SKILL.md
# - references/

# Rebuild if needed
skill-seekers create --config my-config --skip-scrape

# Or recreate
skill-seekers create <source>

---

"Target platform not supported"

Cause: Typo in target name

Solution:

# List valid targets
skill-seekers package --help

# Valid targets:
# claude, gemini, openai, langchain, llama-index,
# haystack, pinecone, chroma, weaviate, qdrant, faiss, markdown

---

"Out of memory"

Cause: Skill too large for available RAM

Solution:

# Use streaming mode
skill-seekers package output/my-skill/ --streaming

# Reduce chunk size
skill-seekers package output/my-skill/ \
  --streaming \
  --streaming-chunk-chars 1000

---

Upload Issues

"Upload failed: Invalid API key"

Cause: Wrong or missing API key

Solution:

# Claude
export ANTHROPIC_API_KEY=sk-ant-...

# Gemini
export GOOGLE_API_KEY=AIza...

# OpenAI
export OPENAI_API_KEY=sk-...

# Verify
echo $ANTHROPIC_API_KEY

---

"Upload failed: Network error"

Cause: Connection issues

Solution:

# Check connection
ping api.anthropic.com

# Retry
skill-seekers upload output/my-skill-claude.zip --target claude

# Or upload manually through web interface

---

"Upload failed: File too large"

Cause: Package exceeds platform limits

Solution:

# Check size
ls -lh output/my-skill-claude.zip

# Use streaming mode
skill-seekers package output/my-skill/ --streaming

# Or split into smaller skills
skill-seekers workflows split-config configs/my-config.json

---

GitHub Issues

"GitHub API rate limit"

Cause: Unauthenticated requests limited to 60/hour

Solution:

# Set token
export GITHUB_TOKEN=ghp_...

# Create token: https://github.com/settings/tokens
# Needs: repo, read:org (for private repos)

---

"Repository not found"

Cause: Private repo or wrong name

Solution:

# Check repo exists
https://github.com/owner/repo

# Set token for private repos
export GITHUB_TOKEN=ghp_...

# Correct format
skill-seekers github --repo owner/repo

---

"No code found"

Cause: Empty repo or wrong branch

Solution:

# Check repo has code

# Specify branch in config
{
  "type": "github",
  "repo": "owner/repo",
  "branch": "main"
}

---

PDF Issues

"PDF is encrypted"

Cause: Password-protected PDF

Solution:

# Add password to config
{
  "type": "pdf",
  "pdf_path": "protected.pdf",
  "password": "secret123"
}

---

"OCR failed"

Cause: Scanned PDF without OCR

Solution:

# Enable OCR
skill-seekers pdf --pdf scanned.pdf --enable-ocr

# Install OCR dependencies
pip install skill-seekers[pdf-ocr]
# System: apt-get install tesseract-ocr

---

Configuration Issues

"Invalid config JSON"

Cause: Syntax error in config file

Solution:

# Validate JSON
python -m json.tool configs/my-config.json

# Or use online validator
# jsonlint.com

---

"Config not found"

Cause: Wrong path or missing file

Solution:

# Check file exists
ls configs/my-config.json

# Use absolute path
skill-seekers create --config /full/path/to/config.json

# Or list available
skill-seekers estimate --all

---

Performance Issues

"Scraping is too slow"

Solutions:

# Use async mode
skill-seekers create <url> --async --workers 5

# Reduce rate limit (for your own servers)
skill-seekers create <url> --rate-limit 0.1

# Skip enhancement
skill-seekers create <url> --enhance-level 0

---

"Out of disk space"

Solutions:

# Check usage
du -sh output/

# Clean old skills
rm -rf output/old-skill/

# Use streaming mode
skill-seekers create <url> --streaming

---

"High memory usage"

Solutions:

# Use streaming mode
skill-seekers create <url> --streaming
skill-seekers package output/my-skill/ --streaming

# Reduce workers
skill-seekers create <url> --workers 1

# Limit pages
skill-seekers create <url> --max-pages 100

---

Getting Help

Debug Mode

# Enable verbose logging
skill-seekers create <source> --verbose

# Or environment variable
export SKILL_SEEKERS_DEBUG=1

Check Logs

# Enable file logging
export SKILL_SEEKERS_LOG_FILE=/tmp/skill-seekers.log

# Tail logs
tail -f /tmp/skill-seekers.log

Create Minimal Reproduction

# Create test config
cat > test-config.json << 'EOF'
{
  "name": "test",
  "base_url": "https://example.com/",
  "max_pages": 5
}
EOF

# Run with debug
skill-seekers create --config test-config.json --verbose --dry-run

---

Report an Issue

If none of these solutions work:

1. Gather info:

   skill-seekers --version
   python --version
   pip show skill-seekers
   

2. Enable debug:

   skill-seekers <command> --verbose 2>&1 | tee debug.log
   

3. Create issue:

   • https://github.com/yusufkaraaslan/Skill_Seekers/issues
   • Include: error message, command used, debug log

---

Error Reference

Error Code	Meaning	Solution
E001	Config not found	Check path
E002	Invalid config	Validate JSON
E003	Network error	Check connection
E004	Rate limited	Slow down or use token
E005	Scraping failed	Check selectors
E006	Enhancement failed	Check API key
E007	Packaging failed	Check skill structure
E008	Upload failed	Check API key

---

Still Stuck?

• Documentation: https://skillseekersweb.com/
• GitHub Issues: https://github.com/yusufkaraaslan/Skill_Seekers/issues
• Discussions: Share your use case

---

Last updated: 2026-02-16