🔧 Troubleshooting¶

Comprehensive solutions for common issues, debugging techniques, and performance optimization

Quick Fixes

Having urgent issues? Try these emergency fixes first:

# Nuclear option - clean everything and rebuild
rxiv clean --all && rxiv pdf

# Debug mode - see what's failing
rxiv pdf --verbose

# Skip validation - quick build to test
rxiv pdf --skip-validation

Installation Issues¶

Package Installation Problems¶

Problem: rxiv command not found

Symptoms: bash: rxiv: command not found or similar error

Solutions:

# Check if rxiv-maker is installed
pip show rxiv-maker

# If installed, add to PATH
export PATH="$HOME/.local/bin:$PATH"  # Linux/macOS
# Add to ~/.bashrc or ~/.zshrc for permanent fix

# Alternative: run directly
python -m rxiv_maker.cli --help

Problem: pip install rxiv-maker fails

ERROR: Could not find a version that satisfies the requirement rxiv-maker

Solutions:

# Update pip first
pip install --upgrade pip

# Install with verbose output
pip install -v rxiv-maker

# Use specific index if needed
pip install --index-url https://pypi.org/simple/ rxiv-maker

Problem: Permission denied during installation

ERROR: Could not install packages due to an PermissionError

Solutions:

# Use user installation
pip install --user rxiv-maker

# Or use pipx (recommended)
pipx install rxiv-maker

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install rxiv-maker

Installation Problems (Ubuntu/Debian/macOS)¶

Note: As of January 2025, Rxiv-Maker is distributed exclusively via pip/pipx. Legacy APT/Homebrew methods have been deprecated.

Symptoms: - apt install rxiv-maker fails with "package not found" - brew install rxiv-maker fails - Package manager installation not working

Solutions:

# Ubuntu/Debian (recommended)
sudo apt update
sudo apt install python3-pip pipx texlive-latex-recommended texlive-fonts-recommended
pipx install rxiv-maker

# macOS (recommended)
brew install pipx
brew install --cask mactex-no-gui
pipx install rxiv-maker

# Verify installation
rxiv check-installation

LaTeX/System Dependencies¶

Problem: LaTeX not found

ERROR: pdflatex not found. Please install LaTeX.

Solutions:

macOSUbuntu/DebianWindows

# Install MacTeX
brew install --cask mactex

# Or BasicTeX (smaller)
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install collection-fontsrecommended

sudo apt update
sudo apt install texlive-latex-extra texlive-fonts-recommended

Download and install MiKTeX or TeX Live

Problem: Missing LaTeX packages

LaTeX Error: File `package.sty' not found.

Solutions:

# Install missing packages (macOS/Linux)
sudo tlmgr install package-name

# On MiKTeX (Windows), packages install automatically
# or use MiKTeX Console

Build Issues¶

PDF Generation Problems¶

Problem: Build fails with LaTeX errors

ERROR: LaTeX compilation failed

Debugging steps:

# Run with verbose output
rxiv pdf --verbose

# Check LaTeX log
cat output/main.log

# Clean and rebuild
rxiv clean
rxiv pdf

Problem: Figures not generating

ERROR: Failed to generate figure: FIGURES/plot.py

Solutions:

# Test figure script individually
cd FIGURES
python plot.py

# Check Python environment
python --version
pip list

# Verify file permissions
ls -la FIGURES/

Problem: Citations not working

LaTeX Warning: Citation 'reference' on page 1 undefined

Solutions:

# Check BibTeX file format
rxiv validate

# Verify citation keys
grep "@" 03_REFERENCES.bib

# Rebuild with bibliography
rxiv clean
rxiv pdf

Python Execution Issues¶

Problem: Python code blocks fail

ERROR: Python execution failed in code block

Solutions:

# Check Python syntax
python -m py_compile your_script.py

# Test environment
python -c "import pandas, matplotlib, numpy"

# Check Python path
which python
python --version

Problem: Module import errors

ModuleNotFoundError: No module named 'pandas'

Solutions:

# Install required packages
pip install pandas matplotlib seaborn scipy numpy

# Or install from requirements file
pip install -r requirements.txt

# Check virtual environment
which python
pip list

Validation Issues¶

Structure Validation¶

Problem: Validation fails

ERROR: Manuscript structure is invalid

Common fixes:

# Check required files exist
ls -la 01_MAIN.md 03_REFERENCES.bib 00_CONFIG.yml

# Validate YAML config
python -c "import yaml; yaml.safe_load(open('00_CONFIG.yml'))"

# Check file encoding
file 01_MAIN.md

Problem: Configuration errors

ERROR: Invalid configuration in 00_CONFIG.yml

Solutions:

# Check YAML syntax
title: "Your Title"  # Use quotes for titles with special characters
authors:
  - name: "First Author"
    affiliation: "Institution"

Performance Issues¶

Slow Build Times¶

Problem: PDF generation is very slow

Symptoms: - Build takes several minutes - Figure generation slowness - LaTeX compilation delays

Solutions:

# Only regenerate changed figures (automatic detection)
rxiv pdf

# Skip figure regeneration entirely
rxiv pdf --skip-figures

# Profile build time
time rxiv pdf --verbose

# Skip expensive operations for testing
time rxiv pdf --skip-validation --skip-figures

# Clean old files that may slow things down
rxiv clean

Figure Generation Optimization:

# Use figure caching (default, but ensure it's enabled)
export RXIV_CACHE_FIGURES=1

# Parallel figure generation
export RXIV_PARALLEL_JOBS=4  # Adjust based on CPU cores

Problem: Large file sizes

Solutions:

# Optimize images
# In your Python figures:
plt.savefig('figure.png', dpi=300, optimize=True, bbox_inches='tight')

# Compress PDFs
# Install ghostscript, then:
gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/screen \
   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=compressed.pdf input.pdf

Memory Issues¶

Problem: Out of memory during build

Symptoms: - System slowdown during builds - Out of memory errors - Process killed unexpectedly

Solutions:

# In figure scripts, optimize memory usage
import matplotlib
matplotlib.use('Agg')  # Use non-interactive backend

# Configure matplotlib for memory efficiency
plt.rcParams['figure.max_open_warning'] = 0
plt.rcParams['agg.path.chunksize'] = 10000

# Process data in chunks
for chunk in pd.read_csv('large_file.csv', chunksize=1000):
    process_chunk(chunk)

# Use context manager for automatic cleanup
with plt.subplots(figsize=(8, 6)) as (fig, ax):
    # Your plotting code here
    x = np.random.randn(10000)
    ax.hist(x, bins=50, alpha=0.7)
    plt.tight_layout()
    plt.show()

# Explicitly clean up
plt.close('all')

System-level solutions:

# Monitor memory usage
htop

# Add swap space (Linux)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Platform-Specific Issues¶

macOS Issues¶

Problem: "Developer cannot be verified" error

# Allow app in System Preferences > Security & Privacy
# Or remove quarantine attribute
xattr -r -d com.apple.quarantine /path/to/file

Problem: Homebrew permissions

# Fix Homebrew permissions
sudo chown -R $(whoami) /usr/local/Cellar
brew doctor

Windows Issues¶

Problem: Long path names

# Enable long paths in Windows 10+
# Run as administrator:
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Problem: PowerShell execution policy

# Allow script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Linux Issues¶

Problem: Font rendering issues

# Install additional fonts
sudo apt install fonts-liberation fonts-liberation2

# Clear font cache
fc-cache -f -v

Problem: Permission issues with virtual environments

# Fix permissions
chmod -R u+w venv/
# Or recreate virtual environment
rm -rf venv
python -m venv venv

VS Code Extension Issues¶

Extension Not Working¶

Problem: Syntax highlighting not working

Solutions:

// In VS Code settings.json
{
  "files.associations": {
    "01_MAIN.md": "rxiv-markdown",
    "02_SUPPLEMENTARY_INFO.md": "rxiv-markdown"
  }
}

Problem: Commands not found

Solutions:

# Ensure rxiv is in PATH
which rxiv
echo $PATH

# Reload VS Code window
# Ctrl+Shift+P > "Developer: Reload Window"

Git and Collaboration Issues¶

Version Control Problems¶

Problem: Large file issues

# Use Git LFS for large files
git lfs track "*.pdf"
git lfs track "data/*.csv"
git add .gitattributes

Problem: Merge conflicts in generated files

# Add to .gitignore
output/
*.pdf
*.aux
*.log
*.fls
*.fdb_latexmk

GitHub Actions Issues¶

Problem: CI builds failing

Common solutions:

# Ensure proper Python setup
- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

# Cache dependencies
- name: Cache pip dependencies
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}

Advanced Debugging¶

Enable Debug Mode¶

# Maximum verbosity
export RXIV_DEBUG=1
export RXIV_LOG_LEVEL=DEBUG
rxiv pdf --verbose > debug.log 2>&1

# Analyze the debug log
less debug.log
grep -i error debug.log
grep -i warning debug.log

Container Debugging¶

For containerized builds using docker-rxiv-maker:

# Access container for debugging
docker run -it --rm \
  -v $(pwd):/workspace \
  henriqueslab/rxiv-maker:latest \
  bash

# Inside container
cd /workspace
rxiv pdf --verbose

See the docker-rxiv-maker repository for more details.

Custom Debug Scripts¶

Create a debug script to gather environment information:

# scripts/debug_environment.py
import sys
import os
import subprocess
from pathlib import Path

def debug_environment():
    print("=== Rxiv-Maker Environment Debug ===")

    # Python information
    print(f"Python version: {sys.version}")
    print(f"Python executable: {sys.executable}")

    # Path information
    print(f"Current directory: {os.getcwd()}")
    print(f"PATH: {os.environ.get('PATH', 'Not set')}")

    # Rxiv-Maker installation
    try:
        import rxiv_maker
        print(f"Rxiv-Maker version: {rxiv_maker.__version__}")
        print(f"Rxiv-Maker location: {rxiv_maker.__file__}")
    except ImportError as e:
        print(f"❌ Rxiv-Maker import error: {e}")

    # System tools
    tools = ['pdflatex', 'python', 'docker']
    for tool in tools:
        result = subprocess.run(['which', tool],
                              capture_output=True, text=True)
        if result.returncode == 0:
            print(f"✅ {tool}: {result.stdout.strip()}")
        else:
            print(f"❌ {tool}: Not found")

if __name__ == "__main__":
    debug_environment()

Getting Help¶

Before Asking for Help¶

Please gather this information:

# System information
rxiv --version
python --version
pdflatex --version
uname -a  # Linux/macOS

# Generate debug report
rxiv check-installation > debug_report.txt
rxiv validate --detailed >> debug_report.txt
rxiv pdf --verbose &>> debug_report.txt

# Environment details
pip list
echo $PATH

Common Commands for Debugging¶

# Reset everything
rxiv clean
rm -rf output/
rm -rf __pycache__/

# Validate step by step
rxiv validate --detailed
rxiv validate --fix-common

# Test individual components
python FIGURES/your_figure.py
pdflatex --version

Where to Get Help¶

GitHub Issues - Bug reports and feature requests
GitHub Discussions - Community Q&A
Documentation - Complete guides and tutorials
Examples Repository - Working examples

Before Submitting Issues¶

Check if the issue is already reported
Update to the latest version: pip install --upgrade rxiv-maker
Try a clean build: rxiv clean && rxiv pdf
Include complete error messages and system information
Provide a minimal example that reproduces the issue

FAQ¶

Q: Can I use Rxiv-Maker with Overleaf? A: Rxiv-Maker generates LaTeX, so you can copy the generated .tex files to Overleaf. However, you'll lose the automated figure generation.

Q: How do I update Rxiv-Maker? A: pip install --upgrade rxiv-maker

Q: Can I customize the LaTeX template? A: Yes, see the LaTeX Injection guide for details.

Q: Does Rxiv-Maker work with R? A: Yes, you can create R figure scripts in the FIGURES/ directory with .R extension.

Q: How do I cite Rxiv-Maker? A: See our citation information.

Still having issues? - Check our GitHub Discussions - Report bugs in GitHub Issues - Join our community for help and support!