Improve error messages surrounding notebooks

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/8920

^{Originally posted by nickvigilante February 28, 2024}

Description

This isn't so much a bug but a request to improve the error messages surrounding notebooks. The common thread between the two issues is to make it easier to identify the file (and the line in the file) that causes issues when running quarto preview or quarto render.

Issue 1

I'm new to Jupyter notebooks and Quarto in general, so I thought I'd be able to get away with running touch notebook.ipynb to create a new notebook that I know I'll need to write later.

I recognize that running touch notebook.ipynb && jupyter execute notebook.ipynb throws an error, and now I know I can't create notebooks using touch.

Despite that, here's what I get when running quarto preview:

(miniconda3)➜  empty-notebook quarto preview
Preparing to preview
ERROR: SyntaxError: Unexpected end of JSON input

Stack trace:
    at JSON.parse (<anonymous>)
    at Object.target (file:///Applications/quarto/bin/quarto.js:38264:27)
    at fileExecutionEngineAndTarget (file:///Applications/quarto/bin/quarto.js:41258:33)
    at renderContexts (file:///Applications/quarto/bin/quarto.js:72183:38)
    at Object.renderFormats (file:///Applications/quarto/bin/quarto.js:72234:28)
    at file:///Applications/quarto/bin/quarto.js:73380:91
    at withRenderServices (file:///Applications/quarto/bin/quarto.js:72589:12)
    at readBaseInputIndex (file:///Applications/quarto/bin/quarto.js:73380:27)
    at inputTargetIndex (file:///Applications/quarto/bin/quarto.js:73368:25)
    at resolveInputTarget (file:///Applications/quarto/bin/quarto.js:73482:25)
(miniconda3)➜  empty-notebook

If this one notebook is buried among several other notebook files, it's not clear which one is the problematic notebook just by looking at this error message alone. What might be nice is a message like this:

ERROR: SyntaxError: Unable to render 'path/to/notebook.ipynb'
Caused by: Unexpected end of JSON output

Stack trace:
...

That way, I know exactly which notebook is malformed and can take steps to fix it, hopefully speeding up my own troubleshooting.

This is also applicable to a case where there might have been an unexplained issue when saving the notebook, or if someone manually edited the notebook JSON. Just giving the user a clue about the file where the issue is happening would be immensely helpful.

Issue 2

I created a notebook with two cells. The label of the first cell is test-1, and the second cell has no label (a forced typo for illustrative purposes).

I used the embed shortcode to embed the two cells in a document:

{{< embed notebook.ipynb#test-1 echo=true >}}

{{< embed notebook.ipynb#test-2 echo=true >}}

When I run quarto preview, I get the following message:

(miniconda3)➜  json-issue git:(main) ✗ quarto preview
Preparing to preview
[1/1] index.qmd
ERROR: The cell test-2 does not exist in notebook

Stack trace:
    at file:///Applications/quarto/bin/quarto.js:69687:23
    at Array.map (<anonymous>)
    at notebookMarkdown (file:///Applications/quarto/bin/quarto.js:69684:40)
    at eventLoopTick (ext:core/01_core.js:183:11)
    at async replaceNotebookPlaceholders (file:///Applications/quarto/bin/quarto.js:69628:32)
    at async renderPandoc (file:///Applications/quarto/bin/quarto.js:69987:28)
    at async Object.onRender (file:///Applications/quarto/bin/quarto.js:77261:36)
    at async renderFileInternal (file:///Applications/quarto/bin/quarto.js:77238:17)
    at async renderFiles (file:///Applications/quarto/bin/quarto.js:77062:17)
    at async renderProject (file:///Applications/quarto/bin/quarto.js:77389:25)
(miniconda3)➜  json-issue git:(main) ✗ 

Here are the things that tripped me up:

1. It took testing and experimentation to recognize that [1/1] index.qmd does not mean that the document rendered correctly. I didn't assume the error message applied to index.qmd. I had assumed that [X/Y] path/to/file.qmd meant that path/to/file.qmd had successfully rendered.
2. Because of point 1, seeing "The cell X does not exist in the notebook" was unhelpful, because I'm importing several notebooks, each of which [should] have a cell with label X in the notebook.

In this situation, I think the following could benefit others:

• An explicit reference to the file where the error exists.
• An explicit reference to the line in the file causing the error (which would also imply the notebook that's missing the label).
• An explicit reference to the path to the notebook that's missing the label.

Something like this:

(miniconda3)➜  json-issue git:(main) ✗ quarto preview
Preparing to preview
[1/1] index.qmd
ERROR: Error when rendering path/to/index.qmd:
Line 13: {{< embed notebook-1.ipynb#test-2 echo=true >}}
Caused by: The cell test-2 does not exist in path/to/notebook-1.ipynb

Stack trace:
...

Having the above would have made (and will continue to make, if implemented) troubleshooting easier.

Thanks for your consideration!

Start by reproducing both cases with quarto preview: an empty notebook.ipynb, and index.qmd containing an embed for a missing cell label. Trace the notebook rendering and embed paths referenced by the stack traces. Done means errors identify the affected QMD or notebook path and, where available, the relevant line and missing cell.