Troubleshooting

Start with juphyter doctor. It names the failing part, and for a Python on the wrong PATH it prints the export line that fixes it.

A kernel stopped working

The kernel records absolute paths to a PHP binary, a Python interpreter, and juphyter itself. Upgrading or removing any of them breaks the kernel, and juphyter doctor marks it fail.

Run juphyter install again with the same --name to record the current paths.
A kernel installed into a project breaks when the project’s vendor directory is deleted. Run composer install in the project, or uninstall the kernel.

No Python can host the kernel

juphyter install looks for an interpreter in this order: the one named by --python, then the one that owns the jupyter command on PATH. When that interpreter has no ipykernel 7, it builds a virtual environment with JupyterLab instead of installing into it.

System and Homebrew Python builds are externally managed, and pip install into them refuses. The virtual environment avoids that.
An environment that already exists at the --create-venv path is reused, and its packages are installed again, so a second run finishes an interrupted one.
A directory at that path that holds something other than an environment is refused.
With --python, the command builds nothing. When the named interpreter has no ipykernel, it prints the pip install command for that interpreter and writes no kernel.

The stop button does nothing

The PHP binary that runs the cells lacks pcntl, or lists its functions in disable_functions. juphyter doctor reports it as a warning. Enable pcntl for that binary, or run juphyter install --php with a binary that has it. Limitations covers what an interrupt can and cannot stop.

Quarto

Quarto cannot find the kernel

ERROR: Jupyter kernel 'php' not found. Known kernels: python3

Quarto’s interpreter has no Jupyter in it, so it can list no kernels. juphyter doctor reports this as Quarto: not ready. and prints the fix. Python interpreters and editors covers how to point Quarto at an interpreter that has Jupyter.

`KeyError: 'path'` with a `kernelspec` block

Quarto accepts the fuller front matter that Jupyter writes into a notebook, but for juphyter it also needs path, the directory that holds kernel.json:

---jupyter:  kernelspec:    name: php85    language: php    display_name: "PHP 8.5"    path: /Users/you/Library/Jupyter/kernels/php85---

Quarto reads path to look for a setup cell beside the kernelspec, which it does for any language it has no built-in support for. jupyter: php85 fills it in, so name the kernel instead of describing it.

`Unknown message type: 'comm_open'`

Every render prints this once. It comes from ipykernel, because the kernel installs no comm manager, and it has no effect on the rendered document. The same absence is why ipywidgets are unsupported.

A new PHP session on every render

Quarto keeps a kernel alive between renders only for languages it can write a setup or cleanup cell for. It has none for PHP, and juphyter install writes none, so each render starts a new PHP session, including with --execute-daemon.

Rendering frozen documents

Quarto looks up a document’s kernel by name before it reads frozen output, so a kernel with that name has to be registered on the rendering machine even when no cell runs. Contributing shows how this repository renders its own site that way.