R code issues

1. Note where the error occurred and what the message was.

   If the error was from purrr::map_chr() in the create-measurement-group-sections chunk, skip to that section in Common errors. This chunk cannot be run interactively and requires additional troubleshooting.

2. Restart R (Cmd/Ctrl + Option/Shift + F10).

3. Run each chunk interactively. If the issue is in the R code, this should recreate the problem so you can interactively debug.

4. Once the error is fixed and the chunk runs successfully, try rendering the report again.

To demonstrate, add a typo in the data file name (washi-dataa.csv instead of washi-data.csv) and try rendering.

1. The Background Jobs pane of RStudio opened with an error message telling us the location and sequence of calls that led to the function that errored.

   Now we know rendering failed at lines 57-66 in the load-data chunk because of the read.csv() function.

processing file: 01_producer-report.qmd
1/61                                    
2/61 [setup]                            
3/61                                    
4/61 [load-data]                        

Quitting from lines 57-66 [load-data] (01_producer-report.qmd)
Error in `file()`:
! cannot open the connection
Backtrace:
 1. utils::read.csv(...)
 2. utils::read.table(...)
 3. base::file(file, "rt")
Execution halted

2. Clear the environment by restarting the R session.

3. Run each chunk interactively. It stops at load-data with a more specific error message informing us that washi-dataa.csv doesn’t exist in the data folder.

   Fix the typo by removing the extra a.

> # Load lab results
> data <- read.csv(
+   here::here("data/washi-dataa.csv"),
+   check.names = FALSE,
+   encoding = "UTF-8"
+ )
Error in file(file, "rt") : cannot open the connection
In addition: Warning message:
In file(file, "rt") :
  cannot open file 'C:/Users/jryan/Documents/R/projects/soils-demo/data/washi-dataa.csv': 
No such file or directory

4. Rerun the chunk. If successful, try rendering the report.

Advanced tip: with your cursor on the function name, press F2 to peek inside the source code of that function. You can also access it through Code > Go to Function Definition. This may help you debug any errors from {soils} functions, or any other package functions. See the RStudio User Guide for more details.

Quarto document issues

Quarto document issues tend to be in the YAML or chunk options. The troubleshooting steps are generally the same as for R code issues.

1. Note where the error occurred and what the message was.

2. Restart R (Ctrl + Shift + F10).

3. Try to address the error.

4. Render again.

To demonstrate, add an extra space before year:.

params:
  producer_id: WUY05
   year: 2023

Rendering fails and we get the following error message telling us we have bad indentation at line 9, column 8.

ERROR: YAMLError: bad indentation of a mapping entry at line 9, column 8:
       year: 2023
           ^

To fix this, delete the extra space and make sure the entries under params: are aligned.

Environment issues

Differences between the Quarto environment and the interactive R environment can cause issues. The most common difference is the working directory. Review the File Paths section in the Quarto primer.

Check the working directory is what you expect by including getwd() in the setup chunk. Running the chunk interactively prints "C:/Users/jryan/Documents/R/projects/soils-demo" in the console, while rendering the report prints "[1] "C:/Users/jryan/Documents/R/projects/soils-demo/template" in the report.

Sometimes the report won’t error, but won’t look as expected. For example, if we move all .qmd files into a subfolder called template, then our report will not have access to the images or resources subdirectories in the main project folder.

When rendering to HTML, the Background Jobs tab will print the below warnings, and the report will not have the fonts and colors specified in styles.css and the images will be missing.

[WARNING] Could not fetch resource resources/styles.css
[WARNING] Could not fetch resource images/logo.png
[WARNING] Could not fetch resource images/physical.png
[WARNING] Could not fetch resource images/biological.png
[WARNING] Could not fetch resource images/chemical.png
Output created: 01_producer-report.html

When rendering to MS Word, the report will fail because it cannot find the word-template.docx.

[WARNING] Could not fetch resource images/logo.png: replacing image with description
[WARNING] Could not fetch resource images/physical.png: replacing image with description
[WARNING] Could not fetch resource images/biological.png: replacing image with description
[WARNING] Could not fetch resource images/chemical.png: replacing image with description
File resources/word-template.docx not found in resource path

The create-measurement-group-sections chunk demonstrates a more complicated environment issue. The chunk runs fine when rendering the report but errors when running interactively.

Invalid parameter values

The parameter values set in the YAML header must exist in your data. Fix this error by either changing params in the YAML or by adding the sample results for that producer_id and year to your data.

Rendering the report with an invalid producer_id and year combination results in the following error message.

Quitting from lines 206-249 [get-producer-info] (01_producer-report.qmd)
Error:
ℹ Update `params` in YAML to a valid `producer_id` and `year` combo.
✖ `Abc` and `2023` must exist in your data.
Backtrace:
Execution halted

Duplicate chunk labels

One common error is duplicated chunk labels, which often occur when copying and pasting code chunks. To fix this issue, change one of the duplicated labels.

If there are two chunks labeled setup, rendering the report will fail with this error.

processing file: 01_producer-report.qmd
Error in parse_block(g[-1], g[1], params.src, markdown_mode) : 
  Duplicate chunk label 'setup', which has been used for the chunk:

create-measurement-group-sections chunk

This chunk is tricky because it is a child template that creates each measurement group section to be inserted into the parent report. To learn more, see the knitr::knit_child() section in the Quarto primer.

> # create-measurement-group-sections
> #| output: asis
>
> sections <- purrr::map_chr(measurement_groups, \(group) {
+   knitr::knit_child(
+     input = "02_section-template.qmd",
+     envir = rlang::env(),
+     quiet = TRUE
+   )
+ })
Error in `purrr::map_chr()`:
ℹ In index: 1.
Caused by error in `setwd()`:
! character argument expected