Lesson 3 of 3  ·  WECA Regional Indicators Workflow

Diagnosing Failures

Reading error messages and fixing the five most common problems

⏱ ~10 minutes

The diagnostic mindset

GitHub Actions failures look alarming but they follow patterns. Every error in this project has a cause, and every cause has a documented fix. The skill is reading the error message and matching it to its cause — then applying the fix with confidence.

There are five errors you are likely to encounter. Study each case, then test yourself in the challenge below.

The five cases

1
"path does not exist: data/raw/…"
Error: `path` does not exist:
  '.../data/raw/4.A.3-data_apprenticeships_starts_05.26.xlsx'
Your chapter source file changed (even a single word edit shifts its hash). Quarto detected a fingerprint mismatch and tried to re-run your R code on GitHub — but your raw data files are not committed, so it can't find them.
Re-render your chapter locally (your raw data must be in data/raw/), then commit the updated freeze snapshot: 
quarto render chapters/0X-topic/index.qmd
git add _freeze/chapters/0X-topic/index/execute-results/html.json
git commit -m "fix: regenerate freeze cache for environment chapter"
git push origin your-branch-name
2
"Updates were rejected"
error: failed to push some refs
hint: Updates were rejected because the remote contains
hint: work that you do not have locally.
Someone else pushed to your branch after your last git pull — or you pushed from a different machine. Git refuses to overwrite commits it doesn't know about.
Pull first to integrate the remote commits, then push: 
git pull origin your-branch-name
git push origin your-branch-name
If you hit a merge conflict, git marks the conflicting file(s) and stops. Open each flagged file and look for conflict markers: 
<<<<<<< HEAD
your local version
=======
the incoming version
>>>>>>> origin/your-branch-name
Edit the file to keep the correct content (delete the markers and the version you don't want), save, then: 
git add the-resolved-file.qmd
git commit -m "fix: resolve merge conflict"
git push origin your-branch-name
For .qmd files, usually keep both sets of changes merged together rather than picking one side.
3
"no changes added to commit"
On branch heather/transport
nothing to commit, working tree clean
# — or —
no changes added to commit (use "git add" and/or "git commit -a")
You ran git commit without running git add first. Nothing was staged, so there was nothing to commit. Or: the file you expected to have changed hasn't actually changed.
Run git status to see what has changed, stage the files you want, then commit: 
git status
git add chapters/0X-topic/index.qmd
git add _freeze/chapters/0X-topic/index/execute-results/html.json
git commit -m "fix: description"
4
"cannot open file 'scripts/R/…'"
Error in source(...): cannot open file
  'scripts/R/01-economy/RI_1E2_population_change.R'
The R script exists on your machine but was never committed to git. GitHub has no copy of it. This often happens when an analyst commits the chapter source but forgets the indicator script and/or the fact CSV.
Stage and commit the missing files. Also double-check the filename matches exactly what the chapter source()s — reversing digit groups (RI_3E1_ vs RI_1E3_) is a common mistake: 
git add scripts/R/01-economy/RI_1E2_population_change.R
git add data/fact/RI_1E2_population_change.csv
git commit -m "fix: add missing indicator script and fact data"
git push origin your-branch-name
5
Pushed to the wrong branch
# You meant to push to heather/transport but pushed to main
# — or committed to your branch when you meant main
You forgot to create or switch to your feature branch before committing. Changes landed on the wrong branch.
Switch to the right branch, get the latest main, re-render if needed, and re-apply your changes: 
git checkout main
git pull origin main
# re-render or re-apply your fix on main (if that's where it belongs)
# — OR — to move commits FROM main TO your branch:
git branch yourname/chapter-name     # create branch from current state
git checkout main
git reset --soft HEAD~1              # undo commit but keep changes staged
git checkout yourname/chapter-name   # switch to correct branch
git commit -m "feat: description"    # re-commit on the right branch

Diagnosis challenge

Given an error message, identify the most likely cause. Click an answer to reveal the explanation.

GitHub Actions fails on your PR with this error. What's the most likely cause?

Error: `path` does not exist: '.../data/raw/RI_5A1_renewable_capacity.xlsx'
A "path does not exist: data/raw/…" error on GitHub always means Quarto tried to re-run your R code — which it only does when the source fingerprint has changed. The freeze cache is out of date. Fix: re-render locally, commit the updated html.json.

You run git push and see this. What must you do first?

error: failed to push some refs to 'origin' hint: Updates were rejected because the remote contains work that you do not have locally.
Git won't let you overwrite remote commits you haven't seen locally. The fix is git pull origin your-branch-name to merge the remote changes, then git push. Never use --force on a shared branch — it destroys other people's work.

The book renders locally but GitHub Actions fails for your chapter with this error. What's missing?

Error in source(...): cannot open file 'scripts/R/05-environment/RI_5A1_renewable_capacity.R'
If a file exists on your machine but not in git, GitHub can't find it. "cannot open file" inside source() on GitHub almost always means the script was never git added. Check: git status to confirm, then git add scripts/R/05-environment/RI_5A1_renewable_capacity.R.

You edit your chapter heading, render successfully, but forget to git add the freeze cache. You commit and push the source file only. What happens?

The cached html.json stores the fingerprint of the version you rendered locally. When you push a different (edited) source without updating the cache, the fingerprint in the stale html.json no longer matches. GitHub tries to re-execute — and fails without your raw data. Always commit the four files together.

The mental model

"path does not exist: data/raw/…" = stale freeze cache. Diagnose by asking: did the source change without a matching cache re-commit? Answer yes → re-render, commit html.json.

Primary source: WORKFLOW_LEARNING_GUIDE.md §Diagnosing and fixing common errors

Have a question? Ask your teacher in this conversation — just type it and continue the session.