pandoc-pdf-error-recovery
Systematic approach to diagnose and recover from pandoc PDF conversion unknown errors
- License 许可
- MIT
- 所属仓库
- HKUDS/AgentPilot
- 最近更新
- 2026-11-12
- Stars
- ★ 8.0k
- Forks
- 944
01 前言 Front Matter
- name
- pandoc-pdf-error-recovery
- description
- Systematic approach to diagnose and recover from pandoc PDF conversion unknown errors
02 资源文件 1
- 其他.skill_id39 B
03 SKILL.md 正文
Pandoc PDF Error Recovery
Overview
When pandoc fails to convert documents to PDF with an "unknown error" or similar vague message, follow this systematic diagnostic and recovery workflow.
Step-by-Step Procedure
1. Verify Pandoc Installation
First confirm pandoc is installed and accessible:
pandoc --version
If this fails, install pandoc before proceeding:
- macOS:
brew install pandoc - Linux:
sudo apt-get install pandocorsudo yum install pandoc - Windows: Download from https://pandoc.org/installing.html
2. Check Available PDF Engines
Identify which PDF rendering engines are available on the system:
which pdflatex xelatex lualatex wkhtmltopdf context
Common engines and their typical use cases:
- pdflatex: Standard LaTeX, fast but limited Unicode support
- xelatex: Full Unicode support, recommended for most modern documents
- lualatex: Lua scripting support, good for complex layouts
- wkhtmltopdf: HTML/CSS rendering, good for web-style documents
- context: ConTeXt typesetting system
3. Attempt Conversion with Explicit Engine
Try conversion with xelatex first (most versatile for general documents):
pandoc input.md -o output.pdf --pdf-engine=xelatex 2>&1 | tee conversion.log
The 2>&1 | tee pattern captures both stdout and stderr to a log file for analysis.
4. Analyze Error Output
If conversion fails, examine the captured log:
cat conversion.log
Common error patterns and solutions:
- Missing LaTeX packages: Install with
tlmgr install <package>or system package manager - Font issues: Specify fonts with
-V mainfont="Font Name" - Missing engine: Fall back to available engine (go to Step 5)
5. Try Alternative Engines
Systematically try other available engines:
# Fallback to pdflatex
pandoc input.md -o output.pdf --pdf-engine=pdflatex 2>&1 | tee conversion-pdflatex.log
# Or try wkhtmltopdf for HTML-rich content
pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf 2>&1 | tee conversion-wkhtmltopdf.log
# Or try lualatex for complex documents
pandoc input.md -o output.pdf --pdf-engine=lualatex 2>&1 | tee conversion-lualatex.log
6. Install Missing Dependencies
If all engines fail or are missing, install required packages:
# Full TeX Live installation (comprehensive but large)
sudo apt-get install texlive-full
# Or minimal installation with common packages
sudo apt-get install texlive-latex-base texlive-fonts-recommended
# For xelatex font support
sudo apt-get install fonts-noto fonts-dejavu
7. Simplify and Retry
If errors persist, try conversion with minimal options:
pandoc input.md -o output.pdf --pdf-engine=xelatex --standalone
Remove complex formatting, custom headers, or advanced LaTeX features that may be causing issues.
Quick Reference Command
Complete diagnostic one-liner:
pandoc --version && which pdflatex xelatex wkhtmltopdf && pandoc input.md -o output.pdf --pdf-engine=xelatex -v
Tips
- Always capture stderr (
2>&1) to see the actual error message - Use
-v(verbose) flag for more detailed output during troubleshooting - For non-English documents, xelatex or lualatex are usually required
- HTML/CSS-heavy documents may work better with wkhtmltopdf
- Check system disk space - PDF generation can require significant temporary space
04 同仓库更多 Skills
agentpilot
Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.
remember
Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.
skill-discovery
Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.
delegate-task
Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.
write-special-chars-ts-check
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.
write-special-chars-readback
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.