Appendix D — Troubleshooting
Keywords
Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering
Problems seen while building and teaching the workshop, and the mistakes Section 5.6 makes on purpose, with fixes that were tested. Reading an error says which line of an error to read first. For setup on Windows, see also the Windows stuck table. For anything not listed: copy the command and the whole error into a web chat with your system’s name, try one suggested fix at a time, and never paste passwords or keys.
Setup
| Problem | Fix |
|---|---|
| Mac: a pop-up asks to install “command line developer tools” | Expected the first time git runs. Click Install and wait (or run xcode-select --install first); if the agent is waiting, tell it done |
command not found for uv, claude, codex or agy just after installing |
Open a new terminal tab. On a Mac, Claude Code’s installer prints a line to add under “Setup notes”: paste it, then open the tab |
quarto: command not found in Ubuntu, though it works in PowerShell |
Windows installers put tools where Ubuntu cannot use them: install Quarto inside Ubuntu (Section 4.5) |
The prompt shows /mnt/c/... |
You are in a Windows folder: cd ~, and keep projects there |
gh auth login or the agent cannot open a browser |
Expected in WSL: copy the link or code it prints into your Windows browser (for gh: github.com/login/device). Codex: codex login --device-auth |
Downloads or git clone fail on a company network |
A proxy can block curl, git and uv: try another network |
git commit says “Please tell me who you are” |
Set your name and email with the two git config --global lines from the setup check |
not a valid Python environment |
A stale .venv: delete it (rm -rf .venv); uv run rebuilds it |
The terminal
| Message | Cause and fix |
|---|---|
zsh: command not found: quatro (Mac) or quatro: command not found (Ubuntu) |
A typo in the command’s name. Press the up arrow, correct it, then Enter (Section 5.6). If the name is right, see the command not found row in Table D.1 |
error: Failed to spawn: `quatro`, then No such file or directory (os error 2) |
The same typo after uv run: uv found no program of that name. Press the up arrow, correct it, then Enter |
bash: cd: too many arguments (Ubuntu) or cd: string not in pwd: my (Mac) |
The folder’s name has a space, so cd read two names: cd "my reports", or type cd my and press Tab (Paths) |
Rendering and preview
| Problem | Cause and fix |
|---|---|
ERROR: No valid input files passed to render |
Quarto found no file of that name in this folder: you are in the wrong folder, or the name is misspelt. pwd and ls show where you are; cd to the project, such as cd ~/first-report (Section 5.6) |
ERROR: YAMLException: …, with numbered lines and a caret (^) |
A mistake in the front matter. YAML often notices it one line after it, so check the line the caret points to and the line above: a missing space after a colon (can not read a block mapping entry), a stray indent (bad indentation of a mapping entry), a missing closing quote (unexpected end of the stream within a double quoted scalar). Fix it by hand, or undo every change since the last commit with git restore report.qmd (Section 5.6) |
readfile 'london.quarto_ipynb', or a locked file |
A render ran while quarto preview was rendering the same file. Let the preview render, or stop it (Ctrl+C) before rendering several formats, then restart it (Section 7.7) |
Typst PDF fails: cannot parse length '60px' |
Typst does not accept CSS pixels in image sizes: write {height=60} or {width="30%"} |
| A Plotly chart appears twice in a dashboard card | The cell both calls fig.show() (or a bare fig.add_…()) and returns the figure: assign, and end the cell with fig |
itables drops rows from a dashboard table |
Its default size limit: show(df, maxBytes=0) |
| A Plotly map is a grey rectangle | The GeoJSON’s rings wind the other way from Plotly’s expectation: reverse them (load_geojson() in the water project’s script) |
| A page shows old numbers after the data changed | freeze: auto reuses results until the page’s own source changes: delete _freeze/ and render again (Section 23.4) |
Python and Jupyter
| Message | Meaning |
|---|---|
quarto check says Jupyter is not available |
Harmless during setup: each project gets its own environment from uv, and Quarto runs Python through uv run |
Kernel is running over TCP without encryption, after [IPKernelApp] WARNING |
Harmless: the connection is between Quarto and a Python process on your own computer |
There is an unactivated Python environment in .venv |
Run Quarto through uv run, which activates the project’s environment |
| A water checkpoint has no data | Water checkpoints hold sources only: cp -R ../quarto-workshop/examples/water/data . |
Backups that copy .venv/ are slow and pointless, because uv run rebuilds it. The checkpoints’ backup command leaves it out, and works on macOS, Linux and WSL:
b="../project-backup-$(date +%Y%m%d-%H%M%S)" && mkdir "$b" && tar -cf - --exclude=.venv . | tar -xf - -C "$b"Publishing
| Problem | Fix |
|---|---|
| The first publish fails: “the remote origin does not have a branch named gh-pages” | The first quarto publish gh-pages must be interactive: run uv run quarto publish gh-pages and press Enter at the question. --no-prompt works once the branch exists |
A push fails with HTTP 400, “RPC failed” |
git config http.postBuffer 524288000, then push again |
| 404 right after publishing | GitHub Pages takes 20 to 60 seconds to deploy: wait a minute and reload (Cmd+Shift+R on a Mac, Ctrl+F5 elsewhere) |
A link checker reports 403 Forbidden for a museum’s site |
Some sites block automated requests: open the link in a browser |