Skip to content

Latest commit

 

History

History
619 lines (429 loc) · 9.67 KB

06-troubleshooting.md

File metadata and controls

619 lines (429 loc) · 9.67 KB

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:

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?

Last updated: 2026-02-16