Missing/null YAML value leads to bad error message

[mcanouil]

If you use the following document (with _quarto.yml):

---
format:
  html:
---

Edit: Here the missing steps to reproduce:

mkdir whatever
cd whatever
echo "---\nformat:\n  revealjs:\n---\n" > index.qmd
quarto render index.qmd # proper error
quarto preview index.qmd # bad error

From an IDE, you get Field "html" has empty value but it must instead be an object but when rendering (edit: via IDE thus preview) you get:

ERROR: TypeError: Cannot read properties of null (reading 'bibliography')

Stack trace:
    at file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:376:29
    at Array.forEach (<anonymous>)
    at fixupMergeableScalars (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:375:8)
    at file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:392:9
    at Array.forEach (<anonymous>)
    at fixupFormat (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:388:27)
    at mergeQuartoConfigs (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:400:5)
    at resolveFormatsFromMetadata (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:122:23)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async resolveFormats (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:482:24)

This error is very missleading and wrong as it should be ERROR: TypeError: Cannot read properties of null (reading 'html') in this case.

Quarto 99.9.9
[✓] Checking environment information...
      Quarto cache location: /Users/mcanouil/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.85.1: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      commit: c6994ae096db9fe3efb07ee190d5c732ba6351dd
      Path: /Users/mcanouil/Projects/quarto/quarto-cli/package/dist/bin

[✓] Checking tools....................OK
      TinyTeX: v2025.03.10
      Chromium: (not installed)

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

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Brave Browser.app/Contents/MacOS/Brave Browser
      Source: QUARTO_CHROMIUM

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

[✓] Checking Python 3 installation....OK
      Version: 3.13.1
      Path: /Users/mcanouil/Projects/quarto/quarto-playground/.venv/bin/python3
      Jupyter: 5.7.2
      Kernels: julia-1.11, python3

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

(/) Checking R installation...........ℹ R version 4.4.3 (2025-02-28)
! Config '~/.Rprofile' was loaded!
[✓] Checking R installation...........OK
      Version: 4.4.3
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Users/mcanouil/Projects/quarto/quarto-playground/renv/library/macos/R-4.4/aarch64-apple-darwin20
        - /Users/mcanouil/Library/Caches/org.R-project.R/R/renv/sandbox/macos/R-4.4/aarch64-apple-darwin20/f7156815
      knitr: 1.50
      rmarkdown: 2.29

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

[cderv]

Sorry to have missed the issue;

From an IDE, you get Field "html" has empty value but it must instead be an object but when rendering you get:

Just to add that I do not get exact same behavior.

I do get validation error for quarto render

❯ quarto render index.qmd
ERROR: Validation of YAML front matter failed.
ERROR: (line 3, columns 3--7) Field "html" has empty value but it must instead be an object
2: format:
3:   html:
        ~
4: ---

ERROR: Render failed due to invalid YAML.

but not for quarto preview where I see same error message as you

So it seems the problem is that we don't get YAML validation error for quarto preview correctly.

@cscheid is this difference expected ? 🤔

More on the biliography error message

This error is very missleading and wrong as it should be ERROR: TypeError: Cannot read properties of null (reading 'html') in this case.

This errors comes from

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

Lines 364 to 380 in e14d224

	const fixupMergeableScalars = (metadata: Metadata) => {
	[
	kBibliography,
	kCss,
	kHeaderIncludes,
	kIncludeBefore,
	kIncludeAfter,
	kIncludeInHeader,
	kIncludeBeforeBody,
	kIncludeAfterBody,
	]
	.forEach((key) => {
	if (typeof (metadata[key]) === "string") {
	metadata[key] = [metadata[key]];
	}
	});
	};

This code part is not handling metadata being null at all. So a "fix" for this could be

diff --git a/src/command/render/render-contexts.ts b/src/command/render/render-contexts.ts
index 8c7ebb6db..7cacde71e 100644
--- a/src/command/render/render-contexts.ts
+++ b/src/command/render/render-contexts.ts
@@ -362,6 +362,9 @@ function mergeQuartoConfigs(

   // bibliography needs to always be an array so it can be merged
   const fixupMergeableScalars = (metadata: Metadata) => {
+    if (metadata === null) {
+      return metadata;
+    }
     [
       kBibliography,
       kCss,

But this is bad fix because YAML validation should be stopping rendering early and null should be not be allowed as user input.

I tried without validation and with the fix, and it will render but to default format (html) because in our formats metadata detection null means to no select (same as false) (from here)

[mcanouil]

I get the same thing (I was in between meetings but did not want to forget to open the issue):

❯ tree
.
└── index.qmd

1 directory, 1 file

❯ quarto render index.qmd 
ERROR: Validation of YAML front matter failed.
ERROR: (line 3, columns 3--11) Field "revealjs" has empty value but it must instead be an object
2: format:
3:   revealjs:
            ~
4: ---

ERROR: Render failed due to invalid YAML.

Stack trace:
    at renderFileInternal (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-files.ts:463:13)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async renderFiles (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-files.ts:325:9)
    at async render (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-shared.ts:104:18)
    at async Command.actionHandler (file:///Users/mcanouil/Projects/quarto/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/quarto-cli/src/quarto.ts:191:5)
    at async file:///Users/mcanouil/Projects/quarto/quarto-cli/src/quarto.ts:220:5
    at async file:///Users/mcanouil/Projects/quarto/quarto-cli/src/core/main.ts:41:14


❯ quarto preview index.qmd # bad error
ERROR: TypeError: Cannot read properties of null (reading 'bibliography')

Stack trace:
    at file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:376:29
    at Array.forEach (<anonymous>)
    at fixupMergeableScalars (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:375:8)
    at file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:392:9
    at Array.forEach (<anonymous>)
    at fixupFormat (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:388:27)
    at mergeQuartoConfigs (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:400:5)
    at resolveFormatsFromMetadata (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:122:23)
    at eventLoopTick (ext:core/01_core.js:175:7)
    at async resolveFormats (file:///Users/mcanouil/Projects/quarto/quarto-cli/src/command/render/render-contexts.ts:482:24)

[cderv]

I was surprised it would mean no validation at all so I tried

format:
  revealjs: 1234

and then we do get validation error even with preview

❯ quartoPreRelease preview index.qmd
ERROR: Validation of YAML front matter failed.
ERROR: In file index.qmd
(line 3, columns 13--16) Field "revealjs" has value 1234, which must instead be an object
2: format:
3:   revealjs: 1234
              ~~~~
4: ---
x The value 1234 is of type number.
i The error happened in location format:revealjs.

ERROR: Render failed due to invalid YAML

so it is some interaction or resolving order.

[cderv]

So this is it, we do ask for formats resolution before any validation happens

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

Lines 282 to 294 in e14d224

	const formats = await (async () => {
	const services = renderServices(nbContext);
	try {
	return await renderFormats(
	file!,
	services,
	undefined,
	project,
	);
	} finally {
	services.cleanup();
	}
	})();

and in fact, for render we do have a specific validation when an error happens before validation

quarto-cli/src/command/render/render-files.ts

Lines 448 to 468 in e14d224

	} catch (e) {
	// bad YAML can cause failure before validation. We
	// reconstruct the context as best we can and try to validate.
	// note that this ignores "validate-yaml: false"
	const { engine, target } = await fileExecutionEngineAndTarget(
	file.path,
	options.flags,
	project,
	);
	const validationResult = await validateDocumentFromSource(
	target.markdown,
	engine.name,
	error,
	);
	if (validationResult.length) {
	throw new RenderInvalidYAMLError();
	} else {
	// rethrow if no validation error happened.
	throw e;
	}
	}

This is why it is working with quarto render

fixing the bibliography problem would definitely help, but still ... maybe we should do the same in preview as in render regarding catching error and validating 🤔

[cderv]

fixing the bibliography problem would definitely help,

I have made a change for this in

• avoid cryptic error message because of internal function not handling null value #12372

which now surface the correct YAML validation message.

maybe we should do the same in preview as in render regarding catching error and validating

But maybe this would be the better fix long term