73adda0b17
Replace all occurrences of old ambiguous flag names with the new explicit ones: --chunk-size (tokens) → --chunk-tokens --chunk-overlap → --chunk-overlap-tokens --chunk → --chunk-for-rag --streaming-chunk-size → --streaming-chunk-chars --streaming-overlap → --streaming-overlap-chars --chunk-size (pages) → --pdf-pages-per-chunk Updated: CLI_REFERENCE (EN+ZH), user-guide (EN+ZH), integrations (Haystack, Chroma, Weaviate, FAISS, Qdrant), features/PDF_CHUNKING, examples/haystack-pipeline, strategy docs, archive docs, and CHANGELOG. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
620 lines
9.7 KiB
Markdown
620 lines
9.7 KiB
Markdown
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Increase timeout
|
|
skill-seekers create <url> --timeout 60
|
|
|
|
# Or in config
|
|
{
|
|
"timeout": 60
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### "SSL certificate error"
|
|
|
|
**Cause:** Certificate validation failure
|
|
|
|
**Solution:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Add password to config
|
|
{
|
|
"type": "pdf",
|
|
"pdf_path": "protected.pdf",
|
|
"password": "secret123"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### "OCR failed"
|
|
|
|
**Cause:** Scanned PDF without OCR
|
|
|
|
**Solution:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Enable verbose logging
|
|
skill-seekers create <source> --verbose
|
|
|
|
# Or environment variable
|
|
export SKILL_SEEKERS_DEBUG=1
|
|
```
|
|
|
|
### Check Logs
|
|
|
|
```bash
|
|
# Enable file logging
|
|
export SKILL_SEEKERS_LOG_FILE=/tmp/skill-seekers.log
|
|
|
|
# Tail logs
|
|
tail -f /tmp/skill-seekers.log
|
|
```
|
|
|
|
### Create Minimal Reproduction
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
skill-seekers --version
|
|
python --version
|
|
pip show skill-seekers
|
|
```
|
|
|
|
2. **Enable debug:**
|
|
```bash
|
|
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*
|