Skill v1.0.2
Automated scan100/1001 files
version: "1.0.2" name: pandoc-pdf-error-resolution description: Systematic debugging workflow for pandoc PDF conversion errors
Pandoc PDF Error Resolution
This skill provides a step-by-step workflow for diagnosing and resolving "unknown error" messages when using pandoc to generate PDFs.
When to Use
Use this skill when:
- Pandoc returns an "unknown error" during PDF conversion
- The conversion succeeds for other formats (e.g., markdown, HTML) but fails for PDF
- You need to identify which PDF engine is available and working
Step-by-Step Procedure
Step 1: Verify Pandoc Installation
First, confirm pandoc is installed and check its version:
pandoc --version
This confirms pandoc is available and shows the version number. Note that pandoc itself doesn't generate PDFs directly—it delegates to external PDF engines.
Step 2: Check Available PDF Engines
Identify which PDF engines are installed on the system:
which pdflatex xelatex lualatex wkhtmltopdf pdfroff 2>/dev/null || echo "Checking individual engines..."which pdflatexwhich xelatexwhich lualatexwhich wkhtmltopdf
Common engines and their characteristics:
- pdflatex: Fast, widely available, good for basic documents
- xelatex: Better Unicode/font support, recommended for complex documents
- lualatex: Advanced typography, Lua scripting support
- wkhtmltopdf: HTML-to-PDF conversion, good for web-style documents
Step 3: Attempt Conversion with Explicit Engine
Retry the conversion with an explicit --pdf-engine flag:
pandoc input.md -o output.pdf --pdf-engine=xelatex
Try engines in this order:
xelatex(best Unicode support)pdflatex(most widely available)lualatex(if xelatex fails)wkhtmltopdf(for HTML-heavy content)
Step 4: Capture Full stderr Output
Always capture the complete error output before falling back:
pandoc input.md -o output.pdf --pdf-engine=xelatex 2>&1 | tee pandoc_error.log
This preserves the full error message for analysis. Common error patterns:
- Font errors: Missing LaTeX packages or fonts
- Package errors: Missing LaTeX packages (use
tlmgr install <package>) - Syntax errors: Issues in the source document
Step 5: Install Missing Dependencies (if needed)
If errors indicate missing LaTeX packages:
# For TeX Livetlmgr install <package-name># For Debian/Ubuntuapt-get install texlive-latex-extra texlive-fonts-recommended# For macOS with Homebrewbrew install --cask mactex
Step 6: Fallback Strategies
If all engines fail, consider:
- Convert to HTML first, then use wkhtmltopdf
- Simplify the document (remove complex formatting)
- Use an online conversion service
- Generate PDF from a different format (e.g., DOCX via LibreOffice)
Example Complete Workflow
#!/bin/bash# pandoc-pdf-debug.shINPUT_FILE="$1"OUTPUT_FILE="${INPUT_FILE%.md}.pdf"echo "=== Pandoc PDF Conversion Debug ==="echo "Input: $INPUT_FILE"echo "Output: $OUTPUT_FILE"# Step 1: Verify pandocecho -e "\n[1] Checking pandoc version..."pandoc --version | head -1# Step 2: Check enginesecho -e "\n[2] Checking available PDF engines..."for engine in pdflatex xelatex lualatex wkhtmltopdf; doif which "$engine" &>/dev/null; thenecho " ✓ $engine: $(which $engine)"elseecho " ✗ $engine: not found"fidone# Step 3: Try conversion with xelatexecho -e "\n[3] Attempting conversion with xelatex..."pandoc "$INPUT_FILE" -o "$OUTPUT_FILE" --pdf-engine=xelatex 2>&1 | tee /tmp/pandoc_error.logif [ $? -eq 0 ]; thenecho "✓ Conversion successful!"elseecho "✗ Conversion failed. Check /tmp/pandoc_error.log for details"echo "Attempting fallback with pdflatex..."pandoc "$INPUT_FILE" -o "$OUTPUT_FILE" --pdf-engine=pdflatex 2>&1fi
Quick Reference
| Command | Purpose | ||
|---|---|---|---|
pandoc --version | Verify pandoc installation | ||
which xelatex | Check if xelatex engine exists | ||
pandoc file.md -o file.pdf --pdf-engine=xelatex | Convert with explicit engine | ||
| `... 2>&1 \ | tee error.log` | Capture full stderr output | |
tlmgr install <pkg> | Install missing LaTeX package |