`quarto preview` requires trying twice after format change

[mine-cetinkaya-rundel]

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

Changing formats and then clicking on Preview in Positron requires doing this twice before the output format is actually changed.

Steps to reproduce

No response

Actual behavior

No response

Expected behavior

No response

Your environment

• Positron Version: 2026.06.0 build 113
• Mac OS Version 26.5 (25F71)

Quarto check output

Quarto 1.10.3
[✓] Checking environment information...
      Quarto cache location: /Users/mine/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.10.3
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (external install)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

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

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
      Source: MacOS known location

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

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

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

[✓] Checking Python 3 installation....OK
      Version: 3.14.3
      Path: /opt/homebrew/opt/python@3.14/bin/python3.14
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking Julia installation...

[mcanouil]

The issue is not related to Positron.
The preview is not restarted on the first "preview" trigger.

I would say this is more of an issue with the VSCode/Positron extension, as when using CLI, you'll have to manually kill the last preview for a format change to occur in the preview (which could also be seen as an issue).

[mcanouil]

After digging into both quarto-cli and the VS Code/Positron extension, there are two distinct behaviours here as suspected.

When quarto preview watches inputs (the plain CLI case), an input edit fires the file watcher and re-renders through the render(to?) closure, which always reuses the startup flags.to.
So the preview format is fixed for the lifetime of the server and never follows a format: change in the document.
That is by design.

• quarto-cli/src/command/preview/preview.ts

  Line 185 in 57705c3

  const render = async (to?: string) => {

---

Regarding the reported issue, the extension launches preview with --no-watch-inputs and instead drives every render over HTTP to the render-token endpoint.
This is the only path that goes through previewRenderRequestIsCompatible, so the "two triggers" lag is specific to the extension.

• https://github.com/quarto-dev/quarto/blob/e9cfc3c31dd2dd1b1c83f14a61bc713b7f0f4b13/apps/vscode/src/providers/preview/preview.ts#L498

The lag itself (triggered by the extension) is actually rooted in quarto-cli, not the extension.
previewRenderRequestIsCompatible resolves the document format via previewFormat -> renderFormats -> fileExecutionEngineAndTarget.
On a cache hit, fileExecutionEngineAndTarget returns the cached target without re-reading the file, so the front matter parsed at the previous render is reused.

• quarto-cli/src/command/preview/preview.ts

  Lines 359 to 375 in 57705c3

  	export async function previewRenderRequestIsCompatible(
  	request: PreviewRenderRequest,
  	project: ProjectContext,
  	format?: string,
  	) {
  	if (request.version === 1) {
  	return true; // rstudio manages its own request compatibility state
  	} else {
  	const reqFormat = await previewFormat(
  	request.path,
  	project,
  	request.format,
  	undefined,
  	);
  	return reqFormat === format;
  	}
  	}

• quarto-cli/src/command/render/render-contexts.ts

  Line 308 in 57705c3

  export async function renderFormats(

• quarto-cli/src/execute/engine.ts

  Lines 358 to 360 in 57705c3

  	const cached = ensureFileInformationCache(project, file);
  	if (cached && cached.engine && cached.target) {
  	return { engine: cached.engine, target: cached.target };

The fileInformationCache is only invalidated inside renderForPreview, which runs after the compatibility check has already passed.
This makes format-change detection lag exactly one render behind.

• quarto-cli/src/command/preview/preview.ts

  Line 445 in 57705c3

  project.fileInformationCache.invalidateForFile(file);

So after changing format: and clicking Preview, the sequence is:

1. Request 1: the compatibility check reads the cached old format, finds it equal to flags.to, returns 200, and the extension does not restart.
   The render it fires then invalidates and repopulates the cache with the new format, but the output is still the old format.
2. Request 2: the compatibility check now reads the new format, mismatches flags.to, returns 404 (previewUnableToRenderResponse), and the extension falls into its catch and restarts with the new format.

• quarto-cli/src/command/preview/preview.ts

  Line 771 in 57705c3

  await previewRenderRequestIsCompatible(prevReq, project, flags.to)

• quarto-cli/src/command/preview/preview.ts

  Line 778 in 57705c3

  return Promise.resolve(previewUnableToRenderResponse());

• quarto-cli/src/command/render/render-shared.ts

  Line 170 in 57705c3

  export function previewUnableToRenderResponse() {

• https://github.com/quarto-dev/quarto/blob/e9cfc3c31dd2dd1b1c83f14a61bc713b7f0f4b13/apps/vscode/src/providers/preview/preview.ts#L325
• https://github.com/quarto-dev/quarto/blob/e9cfc3c31dd2dd1b1c83f14a61bc713b7f0f4b13/apps/vscode/src/providers/preview/preview.ts#L331

---

There are two possible paths to avoid the double triggers:

• On the quarto-cli side, invalidate the file cache before the compatibility format read, so the first request already sees the new format, returns 404, and the extension restarts on the first trigger.

  • quarto-cli/src/command/preview/preview.ts

    Line 384 in 57705c3

    if (format) {

• On the extension side, resolve the document's declared format and always pass it as ?format=, since a non-empty format argument short-circuits previewFormat before the cache is consulted; today the extension only sends format when one was picked through the format picker.

  • https://github.com/quarto-dev/quarto/blob/e9cfc3c31dd2dd1b1c83f14a61bc713b7f0f4b13/apps/vscode/src/providers/preview/preview.ts#L398
  • https://github.com/quarto-dev/quarto/blob/e9cfc3c31dd2dd1b1c83f14a61bc713b7f0f4b13/apps/vscode/src/providers/preview/preview.ts#L405