🔧 Troubleshooting¶

Common issues and solutions for Rxiv-Maker users. Find quick fixes for installation, build, and workflow problems.

Installation Issues¶

Package Installation Problems¶

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 virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install rxiv-maker

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

Optimizations:

# Skip figure regeneration if unchanged
rxiv pdf --skip-figures

# Use local engine only
rxiv pdf --engine local

# Clean old files
rxiv clean

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

MemoryError: Unable to allocate array

Solutions:

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

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

# Close figures explicitly
plt.close('all')

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') }}

Getting Help¶

Debug Information¶

When asking for help, include:

# System information
rxiv --version
python --version
pdflatex --version

# Environment details
pip list
echo $PATH

# Error logs
rxiv pdf --verbose 2>&1 | tee build.log

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!