# Diagnose and fix nbconvert export failures (PDF, HTML, execution)

Diagnose nbconvert export failures: classify execution-stage failures (CellExecutionError, per-cell timeout) vs conversion-stage failures (missing pandoc, missing xelatex, LaTeX compile errors) from the first error line, then apply the matching fix with the real config keys.

Exact reference: {"kind":"skill_version","skill_id":"skl_rLEJq6RY9y3vrDwBOBwi2g","version_id":"skv_2eU38YZ_LTZJed1FZGvDSQ"}

Applicability: [{"constraint":">=6.0; PDF export additionally requires pandoc >=2.9.2,<4.0.0 and a TeX distribution providing xelatex","technology":"nbconvert","version_scheme":"semver"}]

# Diagnose and fix nbconvert export failures

Use this when `jupyter nbconvert --to pdf notebook.ipynb` (or html, markdown,
slides) fails, or when File > Download as errors with `nbconvert failed`. An
export is two separate stages — executing the notebook, then converting the
result — and each stage fails differently. Classify from the first error line,
then fix that stage.

## 1. Classify: execution failure vs conversion failure

Run the export from the command line (not just the UI) so you see the full
traceback, and read the first distinctive error:

**A. `CellExecutionError`, or `Timeout waiting for execute reply`:** the notebook
itself fails to run. Fix the notebook first (step 2). Note: nbconvert does not
execute by default — this failure only appears with `--execute`.

**B. `PandocMissing: "Pandoc wasn't found. ..."`:** pandoc is missing or too old.
nbconvert needs pandoc >= 2.9.2 and < 4.0.0.

**C. `OSError: "xelatex not found on PATH, if you have not installed xelatex you
may need to do so. ..."`:** PDF export needs a TeX distribution. Install one
(step 3).

**D. `PDF creating failed, captured latex output: ...` / `Failed to run "..."
command:`:** xelatex ran but the LaTeX compile failed. The captured output holds
the real error — usually a missing LaTeX package or a LaTeX error from notebook
content (step 4).

## 2. Execution failures: make the notebook run clean first

Reproduce the execution stage on its own:

```bash
jupyter nbconvert --to notebook --execute notebook.ipynb
```

- `Timeout waiting for execute reply (30s)`: `c.ExecutePreprocessor.timeout`
  defaults to 30 seconds **per cell**. Long-running cells die at this limit;
  raise it in config or split the cell.
- Cells that legitimately raise: pass `--allow-errors` to keep executing and
  export the tracebacks.
- Rule out hidden state before blaming nbconvert: open the notebook and do
  Restart & Run All. A notebook that only works because of out-of-order cell
  execution will fail under nbconvert's clean top-to-bottom run.

## 3. Missing tools: pandoc and TeX

```bash
pandoc --version   # need >= 2.9.2, < 4.0.0
which xelatex
```

Install a TeX distribution (Debian/Ubuntu; see the nbconvert install docs for
other platforms):

```bash
sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic
```

If xelatex is installed but nbconvert can't find it — common when exporting from
the UI, whose server process has a different PATH than your shell — point
nbconvert at it directly with the `c.PDFExporter.latex_command` config key
(step 4).

## 4. LaTeX compile fails: read the captured output

The `PDF creating failed, captured latex output` text is the xelatex log. Read it
for the actual error: most often a missing LaTeX package (install it with
`tlmgr`, apt, or the MiKTeX console) or a LaTeX error triggered by notebook
content such as unescaped special characters. To iterate faster than full PDF
runs, export to LaTeX only and compile by hand:

```bash
jupyter nbconvert --to latex notebook.ipynb
xelatex notebook.tex
```

PDF export config keys (all settable in `jupyter_nbconvert_config.py`):

- `c.PDFExporter.latex_command` — default `["xelatex", "{filename}", "-quiet"]`;
  override with an absolute path if xelatex is not on the server's PATH.
- `c.PDFExporter.latex_count` — how many times xelatex runs (default 3).
- `c.PDFExporter.verbose` — show the latex command output instead of capturing it.
- `c.PDFExporter.texinputs` — extra TEXINPUTS directory for local style files.

## 5. Useful non-PDF exports

```bash
jupyter nbconvert --to html --no-input notebook.ipynb   # hide code cells
jupyter nbconvert --to html --template lab notebook.ipynb
jupyter nbconvert --to markdown notebook.ipynb
jupyter nbconvert --to slides notebook.ipynb --post serve
```

`--stdout` pipes the output instead of writing a file.

## 6. Checklist for the failing export

1. Reproduce from the CLI to get the full traceback, not just the UI's
   `nbconvert failed` summary.
2. Classify: CellExecutionError/timeout vs PandocMissing vs xelatex-not-found
   vs LaTeX compile failure.
3. Execution: fix the notebook, use `--allow-errors`, or raise
   `ExecutePreprocessor.timeout`.
4. Tools: pandoc >= 2.9.2; texlive-xetex plus recommended fonts.
5. LaTeX: read the captured output; export `--to latex` and compile manually
   to iterate.
6. UI-only failures: compare PATH and config between your shell and the
   notebook server process.


## Supporting basis and limitations

Built from the nbconvert source (PDFExporter error strings for xelatex-not-found and LaTeX compile failure, PandocMissing version bounds, ExecutePreprocessor timeout default) and recurring Jupyter Discourse threads on PDF-via-LaTeX export failures.

## Change and rationale

New skill: diagnose and fix nbconvert export failures (PDF, HTML, execution stage).

Notebook export failures (especially 'nbconvert failed: PDF creating failed') are a perennial Jupyter support topic and the error text names the failing stage precisely. This skill teaches agents to read that classification instead of reinstalling blindly, and documents the exact missing-tool errors and PDFExporter/ExecutePreprocessor config keys.