Help request: Preview works fine, but render fails with NotFound

[mfisher87]

Description

I'm attempting to build a slide deck for a presentation, and I'm encountering a confusing error with Quarto 1.4-1.6 (on Ubuntu 22). This presentation is next week and I'm not going to have time to make a minimal example until afterwards. Any help would mean a lot to me.

The source of the problem seems to be my includes. I have used includes before with no issue.

The source is here: https://github.com/mfisher87/presentation-cng2025/tree/10aa28a69f0df8a87918c70720a07018a5a792dd

If you check out the latest commit as of this writing (10aa28a69f0df8a87918c70720a07018a5a792dd) the issue should reproduce. It's reproducing in GitHub Actions on my repo as well.

ERROR: NotFound: No such file or directory (os error 2): rename '/home/robatt/Projects/geojupyter/presentation-cng2025/how-you-can-join.html' -> '/home/robatt/Projects/geojupyter/presentation-cng2025/_site/how-you-can-join.html'

Stack trace:
    at Object.renameSync (ext:deno_fs/30_fs.js:207:7)
    at renderProject (file:///home/robatt/Projects/geojupyter/presentation-cng2025/.pixi/envs/default/bin/quarto.js:77422:22)
    at eventLoopTick (ext:core/01_core.js:183:11)
    at async Command.fn (file:///home/robatt/Projects/geojupyter/presentation-cng2025/.pixi/envs/default/bin/quarto.js:81954:32)
    at async Command.execute (file:///home/robatt/Projects/geojupyter/presentation-cng2025/.pixi/envs/default/bin/quarto.js:8104:13)
    at async quarto (file:///home/robatt/Projects/geojupyter/presentation-cng2025/.pixi/envs/default/bin/quarto.js:114968:5)
    at async file:///home/robatt/Projects/geojupyter/presentation-cng2025/.pixi/envs/default/bin/quarto.js:114986:9

The weird thing is quarto preview works fine, but quarto render fails with the above error.

Thanks in advance to anyone able to look at this 🙏
Matt

[mfisher87]

I was only able to get a successful build by removing lets-chat.md and how-you-can-join.md and all of the includes referencing those files.

[mfisher87]

Oooo! I was able to resolve this by removing the revealjs config from _quarto.yml into slides.qmd (mfisher87/presentation-cng2025@7c8d0ec). This isn't exactly what I want, but it's a small price to pay to get this working again. This feels like a bug to me, but I'm interested to hear if there's a reason for this behavior. I'd like a better error message though! If this is a bug, I'll open an issue once I am done with conference prep and other urgent obligations ... may be mid-late May.

[mcanouil]

This feels like a bug to me, but I'm interested to hear if there's a reason for this behavior

Make a small, simple and fully reproducible example rather than your big project.

[mfisher87]

I did explain that I planned to do that after my conference. As you've seen, I usually do create minimal reproducible examples, but without the time, I figured other users might benefit from this information. Do you agree?

If I had time to do a minimal reproducible example like I usually do, I would have opened an issue instead of a discussion.

[cderv]

@mfisher87 this is a known issue

• output file name conflict when two formats targets same extension (like html and revealjs) #4583
• Getting file not found errror when setting revealjs setting #6809

This is because a single .qmd document will be rendered to format: html AND to format: revealjs and we don't currently handle well formats that will conflict in output name. There are problem in the post processing order of each format while multiple format targets the same output file name.

I was able to resolve this by removing the revealjs config from _quarto.yml into slides.qmd

When you did that, you explicitly stated that slide.qmd should be rendered to revealjs only, and that all other doc like https://github.com/mfisher87/presentation-cng2025/blob/10aa28a69f0df8a87918c70720a07018a5a792dd/how-you-can-join.md should be only html.

Previously, as the how-you-can-join.md did not have a format key specified, all of the ones in _quarto.yml were used, which led to conflict.

Hope it makes sense.

By the way, I do believe that even when the issue will be fixed, I am not sure having both a revealjs output and a html output for how-you-can-join.md will be what you expect.

So you probably need to understand how format merging works to configure the desired format in the right place.
https://quarto.org/docs/projects/quarto-projects.html#shared-metadata

Hope it helps.

[mfisher87]

That makes a lot of sense, thank you for the additional context! My assumption in this case was that how-you-can-join.md would be rendered only in the context of the documents that include it, but I see how that assumption is wrong now.

I don't know how feasible this might be in the short-term, but an error message like this would have been a nice user experience:

foo.md was requested for rendering in multiple formats (html, revealjs) by config in _quarto.yml, which would result in multiple outputs to the same filename.

I'm just on my way out the door for a long drive to Utah, sorry I don't have time to follow up more :)

[cderv]

I don't know how feasible this might be in the short-term, but an error message like this would have been a nice user experience:

Quarto could not really assume that a doc is meant for a single format, could it ?

My assumption in this case was that how-you-can-join.md would be rendered only in the context of the documents that include it, but I see how that assumption is wrong now.

However, I understand now that you did not specifically directly how-you-can-join.md as a render target.
If you only want to use it as an include, I would prefix it with underscore e.g. _how-you-can-join.md so that the document is not considered a separate document for the website.

See https://quarto.org/docs/projects/quarto-projects.html#render-targets

For website, every valid file will be rendered unless configured otherwise: https://quarto.org/docs/websites/#render-targets

So you doc is rendered as it own document (see https://mfisher87.github.io/presentation-cng2025/how-you-can-join)

This is all because the general logic is

• Identify render targets
• Look at all formats in _quarto.yml and render each document to all...
• ...unless a document to render contains only specific format definition in format: key - in that case only render to those, merging document level config with the global format config.

Hope it helps

[mfisher87]

However, I understand now that you did not specifically directly how-you-can-join.md as a render target.
If you only want to use it as an include, I would prefix it with underscore e.g. _how-you-can-join.md so that the document is not considered a separate document for the website.

Awesome, TIL, thank you!!

[mfisher87]

Quarto could not really assume that a doc is meant for a single format, could it ?

I wasn't suggesting it should! :) sorry for being unclear. I'm just thinking that quarto could provide a better error message than "file not found" to help users debug their projects. No rendering behavior would need to be changed, Quarto would only need to detect the case where a conflict would occur. Perhaps this is clearer:

foo.md was requested for rendering in multiple conflicting formats (html, revealjs) by config in _quarto.yml, which would result in multiple outputs to the same filename.