Troubleshooting

This page documents a number of strategies you can employ in case you run into problems with Quarto. As always, we welcome feedback and bug reports on the Quarto issue tracker, but this page might help you get up and running quickly.

Basics

Check the version of quarto and its dependencies

You can check the version of Quarto and its dependencies by running quarto check. Here’s an example of the output it generates:

Quarto 1.6.30
[✓] Checking environment information...
      Quarto cache location: /Users/cscheid/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.6.30
      Path: /Users/cscheid/repos/github/cscheid/quarto-regress/releases/v1.6.30/binQuarto 1.5.42

[✓] Checking tools....................OK
      TinyTeX: v2024.03.13
      Chromium: (not installed)

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

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

[✓] Checking Python 3 installation....OK
      Version: 3.12.1
      Path: /.venv/bin/python3
      Jupyter: 5.7.2
      Kernels: julia-1.10, python3

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

[✓] Checking R installation...........OK
      Version: 4.3.3
      Path: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources
      LibPaths:
        - /Users/username/Library/R/arm64/4.3/library
        - /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library
      knitr: 1.45
      rmarkdown: 2.26

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

Get a stack trace

Setting QUARTO_PRINT_STACK=true in your environment will cause Quarto to print a stack trace when an error occurs.

Windows
Unix

On PowerShell:

$env:QUARTO_PRINT_STACK = "true"

On bash-like shells:

export QUARTO_PRINT_STACK=true

Verbose mode

Quarto will print more information about its internal state if you set QUARTO_LOG_LEVEL=DEBUG in your environment.

Inspect log files

Quarto creates log files that can help you diagnose problems. These are stored in different locations depending on your operating system:

%LOCALAPPDATA%\quarto\logs

${HOME}/Library/Application Support/quarto/logs

If $XDG_DATA_HOME is set, ${XDG_DATA_HOME}/.local/share/quarto/logs, otherwise ${HOME}/.local/share/quarto/logs

Out-of-memory issues

When building a large project or website, you might run into memory limits. In that case, consider adjusting the QUARTO_DENO_V8_OPTIONS environment variable.

In this example, we’re setting the maximum amount of memory to be allocated by Deno to be 8GB. Adjust this to your computer’s limits.

Windows
Unix

On PowerShell:

$env:QUARTO_DENO_V8_OPTIONS = "--max-old-space-size=8192"

On bash-like shells:

export QUARTO_DENO_V8_OPTIONS=--max-old-space-size=8192

Installer issues

macOS

In macOS, installers write their output to /var/log/install.log. Inspecting this file might offer hints to what went wrong.

Warning

If you’re going to ask for help on public forums, be aware that every macOS installer writes to the same file /var/log/install.log. You should make sure you’re not accidentally disclosing installation information you would rather not.

PDF/LaTeX issues

If quarto finds an existing installation of texlive in your system, it will use that. If you’re seeing issues with rendering to PDF, make sure you have an up-to-date installation of texlive. Alternatively, you can have quarto use its own version, by calling quarto install tinytex.

Environment, Libraries, and Dependencies

One common source of tricky problems is the presence of multiple installations of R and Python in a system. Quarto will attempt to find an R or Python installation, and sometimes your shell environment is pointing to a different one.

`knitr`

If you suspect that quarto is finding the wrong version of an R installation, you can obtain information about the R installation that Quarto sees by running the following .qmd file:

---
engine: knitr
---

```{r}
sessionInfo()
Sys.getenv()
.libPaths()

# If the sessioninfo package is available, 
# it provides output that is easier to read,
# and can write its results to a file
sessioninfo:::session_info(to_file = "quarto-session-info-output.txt")
```

You can then also run those commands from your R environment, and compare the output. If sessioninfo is available, then you can ask for a difference between the outputs more directly:

sessioninfo:::session_diff(new = "quarto-session-info-output.txt")

`julia`

One potential source of trouble in Julia execution and installationwith both the jupyter and julia engines are stale library versions in caches. In those situations, consider removing the contents of the directory described under Quarto cache location in quarto check.

Advanced

Debugging Jupyter engine issues

To enable Jupyter debugging, add the following to your YAML front matter:

execute:
  debug: true

Quarto creates a log of the execution of jupyter notebooks in its log directory under jupyter-kernel.log.

If Jupyter execution is hanging instead of failing, you can force immediate flushing of the log by setting QUARTO_JUPYTER_FLUSH_LOGS=true in your environment before running Quarto.

Jupyter appears to find wrong `IJulia` kernel

Jupyter maintains a global list of installed kernels, which Quarto searches with jupyter kernelspec list. Often, Julia installation upgrades will change their paths, and Jupyter’s list of kernelspec files becomes stale. In that case, you will need to explicitly reinstall the IJulia kernel.

Debugging Lua filters

Useful Lua helper functions

Quarto includes a number of useful Lua helper functions that can be used to debug Lua filters. These are available in the quarto module, and can be used as follows:

quarto.log.output(obj) -- prints a potentially complex object to the console

Filter tracing

Setting QUARTO_TRACE_FILTERS=<FILENAME>.json in your environment will cause Quarto to produce a trace of the Lua filters it runs, and write it to disk. This will be a file written to same the directory of the rendered file. We include an interactive Quarto document that can be used to visualize this trace, which you can find in the quarto-cli repository at tools/trace-viewer/trace-viewer.qmd. Run quarto preview trace-viewer.qmd, and you will be shown two text fields, “Trace 1” and “Trace 2”. Drag and drop the JSON file onto either of the fields and you will be shown the trace. If you wish to compare two traces, drag them onto the two fields.