Informative error message if temp csv files are not found during Quarto rendering

Fixes #1012

Author: jgabry

R/fit.R

@@ -1432,11 +1432,29 @@ CmdStanMCMC <- R6::R6Class(
       if (!length(self$output_files(include_failed = FALSE))) {
         stop("No chains finished successfully. Unable to retrieve the draws.", call. = FALSE)
       }
-      csv_contents <- read_cmdstan_csv(
-        files = self$output_files(include_failed = FALSE),
-        variables = variables,
-        sampler_diagnostics = sampler_diagnostics,
-        format = format
+      csv_contents <- tryCatch(
+        read_cmdstan_csv(
+          files = self$output_files(include_failed = FALSE),
+          variables = variables,
+          sampler_diagnostics = sampler_diagnostics,
+          format = format
+        ),
+        error = function(e) {
+          err_msg <- conditionMessage(e)
+          if (isTRUE(getOption("knitr.in.progress")) &&
+              isTRUE(self$runset$args$using_tempdir) &&
+              grepl("File does not exist:", err_msg, fixed = TRUE)) {
+            stop(
+              paste0(
+                err_msg,
+                "\n  If this error happened when using Quarto or Rmarkdown caching,\n",
+                "  see `cmdstanr_output_dir` in `?cmdstanr_global_options`"
+              ),
+              call. = FALSE
+            )
+          }
+          stop(e)
+        }
       )
       private$inv_metric_ <- csv_contents$inv_metric
       private$metadata_ <- csv_contents$metadata

R/options.R

@@ -28,6 +28,9 @@
 #' CSV files when fitting models. The default is a temporary directory. Files in
 #' a temporary directory are removed as part of \R garbage collection, while
 #' files in an explicitly defined directory are not automatically deleted.
+#' Note that using caching with Rmarkdown or Quarto does not store files in a
+#' temporary directory, so we recommend setting `cmdstanr_output_dir` to avoid
+#' failures when re-rendering.
 #'
 #' * `cmdstanr_verbose`: Should more information be printed
 #' when compiling or running models, including showing how CmdStan was called

tests/testthat/test-fit-mcmc.R

@@ -90,6 +90,35 @@ test_that("draws() method returns draws_array (reading csv works)", {
   expect_equal(posterior::variables(draws_beta_alpha), c("beta[1]", "beta[2]", "beta[3]", "alpha"))
 })
 
+test_that("draws() errors with quarto cache guidance for fits created with temp output", {
+  # https://github.com/stan-dev/cmdstanr/issues/1012
+  # https://github.com/stan-dev/cmdstanr/pull/1176
+
+  fit <- testing_fit("logistic", method = "sample", seed = 123, chains = 1)
+  csv_files <- fit$output_files()
+
+  # Simulate a later cached re-render: the fit object still points to the temp
+  # output files, which don't exist anymore
+  unlink(csv_files, force = TRUE)
+  withr::local_options(list(
+    # Even if cmdstanr_output_dir is now set to a non-temp directory,
+    # it was not set when the fit was created so we should still get the error message
+    # that mentions quarto caching
+    cmdstanr_output_dir = test_path("resources"),
+    knitr.in.progress = TRUE
+  ))
+
+  expect_error(
+    fit$draws(),
+    paste0(
+      "Assertion on 'files' failed: File does not exist: '", csv_files[[1]], "'.\n",
+      "  If this error happened when using Quarto or Rmarkdown caching,\n",
+      "  see `cmdstanr_output_dir` in `?cmdstanr_global_options`"
+    ),
+    fixed = TRUE
+  )
+})
+
 test_that("inv_metric() method works after mcmc", {
   x <- fit_mcmc_1$inv_metric()
   expect_length(x, fit_mcmc_1$num_chains())