Troubleshooting¶

Common issues and solutions for Folder2MD4LLMs. If you don't find your issue here, check the Support page for additional help resources.

🚀 Installation Issues¶

Command Not Found¶

Problem: folder2md: command not found

Solutions:

pipx Installationpip Installation

# Check if pipx is in PATH
pipx list

# If pipx is installed but folder2md4llms isn't:
pipx install folder2md4llms

# If PATH issues:
pipx ensurepath
source ~/.bashrc  # or restart terminal

# Check if installed
pip show folder2md4llms

# If installed but not in PATH, use full path:
python -m folder2md4llms.cli

# Or reinstall with --user
pip install --user folder2md4llms

Permission Errors¶

Problem: Permission denied when installing or running

Solutions:

# Use pipx (recommended)
pipx install folder2md4llms

# Or install to user directory
pip install --user folder2md4llms

Python Version Issues¶

Problem: folder2md4llms requires Python 3.11+

Solutions:

# Check Python version
python --version
python3 --version

# Install Python 3.11+ via pyenv
curl https://pyenv.run | bash
pyenv install 3.11.5
pyenv global 3.11.5

# Or use system package manager
# Ubuntu/Debian:
sudo apt update && sudo apt install python3.11

# macOS:
brew install [email protected]

🔧 Configuration Issues¶

Invalid Configuration¶

Problem: ConfigValidationError: Invalid configuration

Solutions:

# Check YAML syntax
python -c "import yaml; yaml.safe_load(open('folder2md.yaml'))"

# Validate configuration
folder2md --config folder2md.yaml --dry-run

# Check for common issues:
# - Indentation (use spaces, not tabs)
# - Missing quotes around special characters
# - Invalid values for enums (strategy names, etc.)

Common fixes:

# ❌ Wrong
token_limit: "80000"  # Should be number, not string
strategy: aggressive  # Should be quoted

# ✅ Correct
token_limit: 80000
strategy: "aggressive"

Pattern Matching Issues¶

Problem: Include/exclude patterns not working as expected

Debug steps:

# Test patterns with dry run
folder2md --dry-run --verbose --include-pattern "src/**/*.py"

# Check what files are being found
folder2md --dry-run --include-pattern "**" | head -20

# Test specific patterns
folder2md --dry-run --include-pattern "*.py"  # Only root level
folder2md --dry-run --include-pattern "**/*.py"  # All levels

Common pattern issues:

# ❌ Wrong patterns
include_patterns:
  - "src/*.py"        # Only direct children of src/
  - "*.{py,js}"       # Missing ** for subdirectories

# ✅ Correct patterns
include_patterns:
  - "src/**/*.py"     # All Python files in src/ and subdirectories
  - "**/*.{py,js}"    # All Python and JS files everywhere

📄 Processing Issues¶

File Not Found Errors¶

Problem: FileNotFoundError or PermissionError when processing

Solutions:

# Check file permissions
ls -la /path/to/file

# Run with verbose mode to see which file causes issues
folder2md --verbose .

# Skip problematic files
folder2md --exclude-pattern "**/problematic-dir/**" .

# Check for broken symlinks
find . -type l -exec file {} \; | grep broken

Memory Issues¶

Problem: MemoryError or system running out of memory

Solutions:

# Reduce file size limits
folder2md --max-file-size 100000 .  # 100KB max

# Disable parallel processing
folder2md --no-parallel .

# Process smaller chunks
folder2md src/ --output src.md
folder2md docs/ --output docs.md

# Use more aggressive condensing
folder2md --smart-condensing --condense-strategy aggressive .

Binary Content Errors¶

Problem: Binary content detected in converter output

Solutions:

# Exclude problematic file types
folder2md --exclude-pattern "**/*.{exe,dll,so,dylib}" .

# Disable document conversion if causing issues
folder2md --no-include-docs .

# Check specific file
file /path/to/problematic/file

🎯 Token Limit Issues¶

Output Too Large¶

Problem: Generated output exceeds LLM context window

Solutions:

# Set strict token limit
folder2md --token-limit 80000 .

# Enable smart condensing
folder2md --smart-condensing --token-limit 80000 .

# Use aggressive condensing
folder2md --smart-condensing --condense-strategy aggressive .

# Focus on specific directories
folder2md src/ --token-limit 40000

Smart Condensing Not Working¶

Problem: Files still too large even with smart condensing

Debug steps:

# Check if languages are supported
folder2md --dry-run --verbose . | grep "condensing"

# Force condensing for specific languages
folder2md --condense-languages python,javascript .

# Check token counting
folder2md --stats --dry-run .

🔄 Document Conversion Issues¶

PDF Conversion Failures¶

Problem: PDF files not converting properly

Solutions:

# Check if PyPDF dependencies are installed
python -c "import pypdf; print('PyPDF available')"

# Try excluding problematic PDFs
folder2md --exclude-pattern "**/problematic.pdf" .

# Disable PDF conversion
folder2md --exclude-pattern "**/*.pdf" .

# Check PDF file
file /path/to/file.pdf
pdfinfo /path/to/file.pdf  # If available

DOCX/Office Document Issues¶

Problem: Office documents not converting

Solutions:

# Check dependencies
python -c "import docx; print('python-docx available')"
python -c "import openpyxl; print('openpyxl available')"

# Install missing dependencies
pip install python-docx openpyxl python-pptx

# Skip problematic documents
folder2md --exclude-pattern "**/*.{docx,xlsx,pptx}" .

🌐 Network and Update Issues¶

Update Check Failures¶

Problem: Errors checking for updates

Solutions:

# Disable update checks
export FOLDER2MD_UPDATE_CHECK=false
folder2md .

# Or in configuration
echo "skip_update_check: true" >> folder2md.yaml

GitHub API Rate Limits¶

Problem: Rate limit errors when checking updates

Solutions:

# Disable update checks temporarily
folder2md --no-update-check .

# Set environment variable permanently
echo 'export FOLDER2MD_UPDATE_CHECK=false' >> ~/.bashrc

🎭 Platform-Specific Issues¶

Windows Issues¶

Problem: Path or encoding issues on Windows

Solutions:

# Use forward slashes in patterns
folder2md --include-pattern "src/**/*.py" .

# Set proper encoding
$env:PYTHONIOENCODING="utf-8"
folder2md .

# Use PowerShell instead of Command Prompt
# Avoid paths with spaces or special characters

macOS Issues¶

Problem: Permission or installation issues

Solutions:

# Use Homebrew installation (recommended)
brew install henriqueslab/folder2md4llms/folder2md4llms

# Or use pipx
pipx install folder2md4llms

Linux Issues¶

Problem: Missing dependencies or library issues

Solutions:

# Install system dependencies
sudo apt update
sudo apt install python3-dev python3-pip

# For CentOS/RHEL
sudo yum install python3-devel python3-pip

# For Arch
sudo pacman -S python python-pip

# Install with all dependencies
pip install folder2md4llms[all]

🔍 Debugging Tips¶

Enable Verbose Logging¶

# Maximum verbosity
export FOLDER2MD_LOG_LEVEL=DEBUG
folder2md --verbose .

# Check what's happening
folder2md --dry-run --verbose . | less

Test with Minimal Configuration¶

# Start simple
folder2md --output test.md --no-smart-condensing src/

# Add features incrementally
folder2md --output test.md --smart-condensing src/
folder2md --output test.md --smart-condensing --include-docs src/

Check System Resources¶

# Monitor memory usage
top -p $(pgrep -f folder2md)

# Check disk space
df -h

# Monitor CPU usage
htop  # or top

🆘 When All Else Fails¶

Create a minimal test case:

mkdir test-folder
echo "print('hello')" > test-folder/test.py
folder2md test-folder/

Collect debug information:

folder2md --version
python --version
uname -a  # Linux/macOS
systeminfo  # Windows

Check the Support page for how to get help
Search existing issues on GitHub
Create a new issue with:
Environment details
Exact commands run
Complete error messages
Minimal reproduction case

Remember: The more specific information you provide, the faster we can help resolve your issue!