Bug Reports

How to make an actionable bug report for Quarto

We want to hear about Quarto bugs and, we want to fix those bugs! The following guidance will help us be as efficient as we can.

Rule 0: Please submit your bug report anyway!

We have a better chance to fix your code quickly if you follow the instructions below. Still, we know that this takes work and isn’t always possible.

We would rather have a record of the problem than not know about it.

We appreciate bug reports even if you are unable to take any or all of the following steps:

Small is beautiful: Aim for a single document with ~10 lines

The most helpful thing you can do to help us is to provide a minimal, self-contained, and reproducible example.

  • minimal: This will often mean turning your large website project into a project with a single small document, and a single large .qmd file into a small (ideally, about 10-20 total lines of code) example. By doing this, you might also be able to learn more specifically what the problem is.
  • self-contained: The more software dependencies we need to understand and install, the harder it is to track the bug down. As you reduce the code, remove as many dependencies as possible.
  • reproducible: If we cannot run your example, we cannot track the bug down. Please make sure the file you submitted is enough to trigger the bug on its own.

Formatting: Make GitHub’s markdown work for us

The easiest way to include a .qmd file in a comment is to wrap it in a code block. To make sure that GitHub doesn’t format your own .qmd, start and end your block with more backticks than you use in your .qmd file. In order to show .qmd files with three backticks (the most common case), use four backticks in your GitHub Issue:

```
This is a code block
```

Sometimes you might need more backticks:

````
This is a four backticks block.

```
This is a code block
```
````

Don’t hold back: Tell us anything you think might make a difference

Although we want the .qmd file to be small, we still can use as much information from you as you’re willing to share. Tell us all!, including:

  • The version of quarto you’re running
  • The operating system you’re running
  • The IDE you’re using, and its version

If you are seeing an error from Quarto, you can also provide additional diagnostic information by defining the QUARTO_PRINT_STACK environment variable.

For example on Unix:

export QUARTO_PRINT_STACK=true
quarto render document.qmd

or on Windows in a Powershell Terminal

$ENV:QUARTO_PRINT_STACK="true"
quarto render document.qmd