Troubleshooting

Common problems and fixes.

This page collects quick fixes and diagnostic commands for the tools used in this course.

---

Quarto isn’t found / Render button doesn’t work

Fix: 1. Install Quarto: https://quarto.org/docs/get-started/
2. Restart RStudio
3. Verify in a terminal:

quarto check
quarto --version

---

PDF render fails (“No TeX installation detected”, missing LaTeX package)

Fix (fastest):

quarto install tinytex

Verify from R:

if (requireNamespace("tinytex", quietly = TRUE)) tinytex::is_tinytex()

---

Quarto tries to render the whole repo

Whitelist only the intended files in site/_quarto.yml:

project:
  type: website
  output-dir: _site
  render:
    - index.qmd
    - pages/**/*.qmd

---

“Files didn’t appear” after running package commands

1. Confirm you are inside your course Project:

   getwd()

2. Refresh the Files pane in RStudio.

3. Check the expected folder manually.

4. Re-run the command and review any error messages.

---

RStudio doesn’t show the Git tab

Enable Git for the Project: Tools → Project Options → Git/SVN (or create the Project from Version Control).

Verify Git is installed and on your PATH:

git --version

---

Git push fails (password prompts, auth errors)

Use HTTPS + Personal Access Token (PAT) or SSH.

• PAT (recommended) Create a PAT and paste it when Git asks for a password. Install Git Credential Manager to cache it.

  • Token docs: https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
  • Git Credential Manager: https://github.com/GitCredentialManager/git-credential-manager

• SSH (alternative) Add your public key in GitHub → Settings → SSH and GPG keys. Docs: https://docs.github.com/authentication/connecting-to-github-with-ssh

---

Website didn’t update on GitHub Pages

• Using GitHub Actions (recommended)

  • Check Actions → Quarto Pages: it should render, upload the artifact, and deploy.
  • Repo Settings → Pages: set Source = GitHub Actions.

• Using branch deployment (/docs)

  • Render locally to docs/ and commit.
  • Repo Settings → Pages: set Source = main /docs.

---

How to Ask for Help

When you encounter a problem, providing good diagnostic information is the fastest way to get it solved. Follow these steps:

1. Describe what you expected to happen and what actually happened.
2. Include the exact error message. Copy and paste it.
3. Provide your system information. Run the following command in the RStudio Console and include the output: r sessionInfo()
4. Provide your tool versions. Run these commands in the RStudio Terminal and include the output: bash quarto --version git --version
5. Include a screenshot. A picture of your full RStudio window (including the error message in the console) is often very helpful.

Finding RStudio Log Files

In rare cases, you may need to check the RStudio log files for more detailed error information.

• Windows: The logs are located in %localappdata%\\RStudio. You can copy and paste that path into your File Explorer address bar.
• macOS: The logs are in ~/.local/share/rstudio. You can find this in the Finder by using the “Go” → “Go to Folder…” menu item.