From a4fa699a820f6ce5643dab2c3c499179d9ee9184 Mon Sep 17 00:00:00 2001 From: upicat Date: Sun, 17 May 2026 13:41:17 +0800 Subject: [PATCH] docs(jupyter-live-kernel): document zmq transport fallback and disable_check_xsrf pitfalls Add two pitfalls discovered when running the skill against a fresh Jupyter server: - Pitfall #9: When the websocket reply channel hangs on every execute even though the kernel actually ran (REST shows execution_state=idle and execution_count increments), force zmq transport with --transport zmq. The zmq transport uses jupyter_client directly and sidesteps the broken websocket layer. - Pitfall #10: A fresh ServerApp rejects POST /api/sessions with "_xsrf argument missing from POST" unless you start it with --ServerApp.disable_check_xsrf=True. Needed for REST-only flows where no browser/cookie is establishing the XSRF token. --- .../data-science/jupyter-notebook/SKILL.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/optional-skills/data-science/jupyter-notebook/SKILL.md b/optional-skills/data-science/jupyter-notebook/SKILL.md index 91ae015f5f4f..17d10c1232b3 100644 --- a/optional-skills/data-science/jupyter-notebook/SKILL.md +++ b/optional-skills/data-science/jupyter-notebook/SKILL.md @@ -160,6 +160,17 @@ uv run "$SCRIPT" restart-run-all --path --save-outputs --compac 8. **Occasional websocket timeouts** — some operations may timeout on first try, especially after a kernel restart. Retry once before escalating. +9. **If websocket consistently times out on this host**, force zmq transport: + `uv run "$SCRIPT" execute --transport zmq ...`. Symptom: every execute returns + "Websocket execution may already have reached the kernel, so auto fallback was + skipped". The kernel actually ran fine (REST shows execution_state=idle and + execution_count increments) — only the websocket reply channel is broken. + zmq transport uses jupyter_client directly and sidesteps the issue. + +10. **When starting a fresh server for REST-only use**, add + `--ServerApp.disable_check_xsrf=True` — otherwise POST /api/sessions returns + `"'_xsrf' argument missing from POST"` and kernel session creation fails. + ## Timeout Defaults The script has a 30-second default timeout per execution. For long-running