template-partials validation does not catch unsupported partial names

[cwickham]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

When a user supplies template-partials, Quarto validates the names against the format's templateContext.partials and requires only that at least one name matches (pandoc.ts#L803-L830). This check gives wrong results in both directions:

1. format: html — unknown names pass silently.
Quarto injects its own title partials (_title-meta-author.html, title-metadata.html, title-block.html) into the document's template-partials metadata (format-html-bootstrap.ts#L192-L198, via format-html-title.ts#L145-L166). readPartials then returns these injected partials together with the user's list, so the injected title-block.html always satisfies the at-least-one check. A misspelled or unsupported partial name renders with no error and no warning, and has no effect on the output.

2. format: revealjs — the error lists partials that do nothing.
When no name matches, the error says:

ERROR: The format 'revealjs' only supports the following partials:
metadata.html
title-block.html
toc.html
styles.html
toc-slide.html
title-slide.html

The first four names come from the shared HTML format extras (format-html.ts#L631-L642), which mergeConfigs concatenates with the two revealjs partials (format-reveal.ts#L236-L247). But the revealjs template never references metadata.html, title-block.html, or toc.html. If you supply one of them, it passes validation and does nothing. (styles.html is referenced by the revealjs template at template.html#L27 and an override works — but the docs only list title-slide.html and toc-slide.html for revealjs.)

The at-least-one rule also means a typo next to one valid partial passes silently in every format.

An AI assistant helped investigate this issue, grounded in a local clone of quarto-cli (per CONTRIBUTING.md "Using AI tools to investigate").

Steps to reproduce

Case 1 — html accepts an unknown partial name silently.

Create bogus.html with the content <!-- bogus partial -->, and render:

---
title: "partials"
format:
  html:
    template-partials:
      - bogus.html
---

Hello.

Case 2 — revealjs accepts a listed partial that has no effect.

Create metadata.html with the content <!-- custom metadata partial -->, and render:

---
title: "partials"
format:
  revealjs:
    template-partials:
      - metadata.html
---

## Slide

Actual behavior

Both documents render with no error and no warning. Neither HTML comment appears in the output — the supplied partials have no effect. (With revealjs, an unlisted name such as bogus.html does error, but the error lists the four HTML-format partials that revealjs does not use.)

Expected behavior

Quarto reports each supplied partial name that the format's template does not use — not only the case where no name matches. The revealjs error message lists only the partials that have an effect for revealjs.

Your environment

• IDE: Positron 2026.08.0 build 213 (renders run from its terminal)
• OS: macOS 26.5.2 (build 25F84)

Quarto check output

Quarto 1.10.18
[✓] Checking environment information...
      Quarto cache location: /Users/charlottewickham/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.10.0: OK
      Dart Sass version 1.101.0: OK
      Deno version 2.7.14: OK
      Typst version 0.15.1: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.10.18
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2026.04
      Chrome Headless Shell: 150.0.7871.115
      VeraPDF: 1.28.2

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/charlottewickham/Library/TinyTeX/bin/universal-darwin
      Version: 2026

[✓] Checking Chrome Headless....................OK
      Using: Chrome Headless Shell installed by Quarto
      Path: /Users/charlottewickham/Library/Application Support/quarto/chrome-headless-shell/chrome-headless-shell-mac-arm64/chrome-headless-shell
      Version: 150.0.7871.115

[✓] Checking basic markdown render....OK

[✓] Checking R installation...........OK
      Version: 4.6.0
      Path: /Library/Frameworks/R.framework/Versions/4.6/Resources
      LibPaths:
        - /Users/charlottewickham/Library/R/arm64/4.6/library
        - /Library/Frameworks/R.framework/Versions/4.6/Resources/library
      knitr: 1.51
      rmarkdown: 2.31

[✓] Checking Knitr engine render......OK

[✓] Checking Python 3 installation....OK
      Version: 3.12.2
      Path: /Users/charlottewickham/.pyenv/versions/3.12.2/bin/python3
      Jupyter: 5.9.1
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking Julia installation...

[mcanouil]

I'm not sure that's a bug as to validate the partials, Quarto would have to list partials from template and partials (you can nest partials).

---
format:
  html:
    template: template.html
    template-partials:
      - bogus.html
---

• template.html

<!DOCTYPE html>

<body>

$bogus.html()$

$body$

</body>

</html>

• bogus.html

<p>Hello, World!</p>

template-partials only check if the path exist, not that it is used.

What's not great is that when the referenced file does not exist in the project, you get a stack trace:

ERROR: Template partial /Users/mcanouil/Projects/quarto-dev/quarto-playground/bogus.html was not found. Please confirm that the path to the file is correct.

Stack trace:
    at file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/template.ts:63:13
    at Array.flatMap (<anonymous>)
    at readPartials (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/template.ts:57:17)
    at runPandoc (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/pandoc.ts:779:26)
    at async renderPandoc (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/render.ts:207:24)
    at async Object.onRender (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/render-files.ts:762:30)
    at async renderFileInternal (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/render-files.ts:724:9)
    at async renderFiles (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/render-files.ts:332:9)
    at async render (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/render-shared.ts:114:18)
    at async Command.actionHandler (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/command/render/cmd.ts:251:26)
    at async Command.execute (https://deno.land/x/cliffy@v1.0.0-rc.3/command/command.ts:1948:7)
    at async Command.parseCommand (https://deno.land/x/cliffy@v1.0.0-rc.3/command/command.ts:1780:14)
    at async quarto (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/quarto.ts:198:5)
    at async file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/quarto.ts:231:5
    at async file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/core/main.ts:45:14
    at async mainRunner (file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/core/main.ts:47:5)
    at async file:///Users/mcanouil/Projects/quarto-dev/quarto-cli/src/quarto.ts:221:3

[mcanouil]

FWIW, with q2, no stack trace, only the error:

Error: failed to read template partial '/work/bogus.html': I/O error: No such file or directory (os error 2)

1 error

Overall, q2 is currently behaving exactly like q1 on this.

[cwickham]

I'm not sure that's a bug as to validate the partials, Quarto would have to list partials from template and partials (you can nest partials).

Ah I see. I was coming from the perspective of: if we require users to use the correct names for partials, we should provide some feedback for cases where they use names we don't recognize. But, you are right, if users can set up new partials, it makes this set of "known partials" hard to know.

That said, I still think this particular message is misleading:

ERROR: The format 'revealjs' only supports the following partials:
metadata.html
title-block.html
toc.html
styles.html
toc-slide.html
title-slide.html

It makes me think we do validation (and we basically don't?) and gives a set or partials where half have no effect on this format.

[mcanouil]

Yes, the error messages / stack trace in all cases are not great.