gh-cadrianmae-claude-marketplace-plugins-pandoc/skills/pandoc/references/troubleshooting.md

Pandoc Troubleshooting Guide

Common errors and solutions for Pandoc document conversion.

YAML Frontmatter Errors

Error: YAML syntax error

Problem: Invalid YAML in frontmatter

Error: YAML syntax error: mapping values are not allowed here

Common Causes:

1. Tabs instead of spaces

   # ❌ Wrong (contains tabs)
   title:→"My Paper"
   
   # ✅ Correct (spaces only)
   title: "My Paper"
   

2. Missing quotes around special characters

   # ❌ Wrong
   title: Paper: A Study
   
   # ✅ Correct
   title: "Paper: A Study"
   

3. Incorrect indentation

   # ❌ Wrong
   author:
   - "Name"  # Should be indented
   
   # ✅ Correct
   author:
     - "Name"
   

Fix: Use validation to find exact error

PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md

Error: YAML not properly closed

Problem: Missing second --- marker

Error: YAML frontmatter not properly closed (missing second '---')

Fix:

---
title: "Paper"
author: "Name"
---     # Must have this!

# Content starts here

Bibliography Errors

Error: Bibliography file not found

Problem: .bib file doesn't exist or wrong path

Error: Bibliography file not found: references.bib

Solutions:

1. Create bibliography file:

   PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
   cp "$PLUGIN_DIR/skills/pandoc/assets/templates/references.bib" references.bib
   

2. Fix path in frontmatter:

   # ❌ Wrong (absolute path from another location)
   bibliography: /old/location/refs.bib
   
   # ✅ Correct (relative path)
   bibliography: references.bib
   bibliography: ./refs/references.bib
   

3. Check file actually exists:

   ls -la references.bib
   

Error: CSL file not found

Problem: Citation style file missing

Error: CSL file not found: harvard.csl

Solutions:

1. Download CSL file:

   # Harvard style
   curl -o harvard.csl https://raw.githubusercontent.com/citation-style-language/styles/master/harvard-cite-them-right.csl
   
   # APA style
   curl -o apa.csl https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl
   
   # IEEE style
   curl -o ieee.csl https://raw.githubusercontent.com/citation-style-language/styles/master/ieee.csl
   

2. Browse all styles: https://github.com/citation-style-language/styles

3. Remove CSL if using default:

   bibliography: references.bib
   # csl: harvard.csl  # Comment out to use default
   

Error: BibTeX parse error

Problem: Invalid BibTeX syntax in .bib file

Common Issues:

1. Missing commas:

   # ❌ Wrong
   @article{key,
     author = "Name"
     title = "Title"    # Missing comma after author
   }
   
   # ✅ Correct
   @article{key,
     author = "Name",   # Comma added
     title = "Title"
   }
   

2. Unclosed braces:

   # ❌ Wrong
   @article{key,
     title = {Unclosed brace
   }
   
   # ✅ Correct
   @article{key,
     title = {Closed brace}
   }
   

3. Invalid characters in cite key:

   # ❌ Wrong
   @article{smith&jones2024,
   
   # ✅ Correct
   @article{smith-jones-2024,
   

PDF Generation Errors

Error: ! LaTeX Error: File not found

Problem: Missing LaTeX packages

Solution:

# Fedora/RHEL
sudo dnf install texlive-scheme-medium

# Ubuntu/Debian
sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended

# macOS
brew install --cask mactex

Error: Unicode characters not supported

Problem: Using pdflatex with Unicode

! Package inputenc Error: Unicode character ... not set up for use with LaTeX

Solution: Use XeLaTeX instead

pandoc document.md -o document.pdf --pdf-engine=xelatex

Or update frontmatter:

# Add to defaults file
pdf-engine: xelatex

Error: Missing fonts

Problem: Custom font not found

! Font ... not found

Solutions:

1. Use standard fonts:

   # Remove custom fonts
   # mainfont: "Custom Font"
   

2. Install font:

   # Copy font to system
   sudo cp font.ttf /usr/share/fonts/
   sudo fc-cache -f -v
   

3. Use XeLaTeX with system fonts:

   mainfont: "Times New Roman"  # Must use XeLaTeX
   

Error: ! Package geometry Error

Problem: Invalid geometry specification

! Package geometry Error: ... is too large

Fix:

# ❌ Wrong
geometry: margin=5in  # Too large for paper

# ✅ Correct
geometry: margin=1in
geometry: "left=1.5in, right=1in, top=1in, bottom=1in"

Image Errors

Error: Image file not found

Problem: Image path incorrect or file missing

Solutions:

1. Use relative paths:

   # ❌ Wrong (absolute path from different location)
   ![](/ old/path/image.png)
   
   # ✅ Correct
   ![](images/figure1.png)
   ![](./assets/diagram.png)
   

2. Check file exists:

   ls -la images/figure1.png
   

3. Create images directory:

   mkdir -p images
   # Copy images there
   

Error: Image format not supported

Problem: LaTeX can't handle certain formats

Supported formats:

• PDF: PNG, JPEG, PDF
• HTML: PNG, JPEG, GIF, SVG

Solution: Convert image format

# Convert SVG to PNG (for PDF output)
convert diagram.svg diagram.png

# Or use ImageMagick
magick convert image.tiff image.png

Conversion Errors

Error: Pandoc not found

Problem: Pandoc not installed or not in PATH

Error: pandoc: command not found

Solution:

# Fedora/RHEL
sudo dnf install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# macOS
brew install pandoc

# Verify installation
pandoc --version

Error: Python not found (validation)

Problem: Python3 not available

Error: python3: command not found

Solution:

# Most Linux distributions have Python3
# But if not:
sudo dnf install python3

# Or use python instead of python3
python --version  # Check if Python 3.x

Error: YAML module not found

Problem: PyYAML not installed (for validation)

ModuleNotFoundError: No module named 'yaml'

Solution:

pip3 install pyyaml

# Or system package
sudo dnf install python3-pyyaml

Output Errors

Error: Permission denied writing output

Problem: Can't write to output location

Error: output.pdf: Permission denied

Solutions:

1. Check write permissions:

   ls -la output.pdf  # Check if file locked
   

2. Use different location:

   pandoc doc.md -o ~/Documents/output.pdf
   

3. Close file in other program:

   • Close PDF viewer
   • Close Word
   • Close text editor

Error: Disk full

Problem: No space for output file

Check:

df -h .  # Check disk space

Solution:

• Free up disk space
• Use different output location

Performance Issues

Slow Conversion

Causes:

1. Large document
2. Many images
3. Complex LaTeX
4. Slow PDF engine

Solutions:

1. Use faster engine:

   # pdflatex is fastest
   pandoc doc.md -o doc.pdf --pdf-engine=pdflatex
   

2. Optimize images:

   # Compress images before embedding
   convert large.png -resize 50% smaller.png
   

3. Split large documents:

   # Convert chapters separately
   pandoc chapter1.md -o chapter1.pdf
   pandoc chapter2.md -o chapter2.pdf
   

Citation Issues

Citations not appearing

Checklist:

1. ✅ Bibliography file exists
2. ✅ CSL file exists (or using default)
3. ✅ Using --citeproc flag
4. ✅ Citation keys match bibliography

Validate:

PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md

Check citation syntax:

# ✅ Correct
[@smith2024]
@jones2023 found that...

# ❌ Wrong
[smith2024]     # Missing @

Wrong citation style

Problem: Citations not in expected format

Solution: Use correct CSL file

csl: harvard.csl  # Harvard
csl: apa.csl      # APA
csl: ieee.csl     # IEEE

Download styles:

curl -o style.csl https://raw.githubusercontent.com/citation-style-language/styles/master/[style-name].csl

Debug Workflow

Step-by-Step Debugging

1. Validate first:

   PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
   python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md
   

2. Check Pandoc version:

   pandoc --version
   # Ensure version 2.0+
   

3. Test minimal conversion:

   # Create minimal test
   echo "# Test" > test.md
   pandoc test.md -o test.pdf
   

4. Add options incrementally:

   # Start simple
   pandoc doc.md -o doc.pdf
   
   # Add engine
   pandoc doc.md -o doc.pdf --pdf-engine=pdflatex
   
   # Add citations
   pandoc doc.md -o doc.pdf --pdf-engine=pdflatex --citeproc
   

5. Check LaTeX intermediate:

   # Generate .tex file to see LaTeX
   pandoc doc.md -o doc.tex
   cat doc.tex  # Inspect for errors
   

Get Help

Pandoc Documentation

• Manual: https://pandoc.org/MANUAL.html
• FAQ: https://pandoc.org/faqs.html
• Demos: https://pandoc.org/demos.html

Community Resources

• Pandoc Discussions: https://github.com/jgm/pandoc/discussions
• Stack Overflow: [pandoc] tag
• LaTeX Stack Exchange: https://tex.stackexchange.com/

Validation Tool

PLUGIN_DIR="~/.claude/marketplaces/cadrianmae-claude-marketplace/plugins/pandoc"
python3 "$PLUGIN_DIR/skills/pandoc/scripts/validate.py" document.md

This tool catches most common errors before conversion.