From df1464ef95f344ed3470cf9b8e15d3b07304f352 Mon Sep 17 00:00:00 2001 From: teknium1 <127238744+teknium1@users.noreply.github.com> Date: Thu, 23 Jul 2026 19:34:38 -0700 Subject: [PATCH] docs(jupyter-notebook): mirror new zmq/xsrf pitfalls to docs pages Regenerate the auto-gen skill page and translate pitfalls 9-10 into the zh-Hans mirror, following the cherry-picked pitfall additions. --- contributors/emails/upicat@users.noreply.github.com | 1 + .../data-science/data-science-jupyter-notebook.md | 11 +++++++++++ .../data-science/data-science-jupyter-notebook.md | 11 +++++++++++ 3 files changed, 23 insertions(+) create mode 100644 contributors/emails/upicat@users.noreply.github.com diff --git a/contributors/emails/upicat@users.noreply.github.com b/contributors/emails/upicat@users.noreply.github.com new file mode 100644 index 000000000000..d0c2fcdd5007 --- /dev/null +++ b/contributors/emails/upicat@users.noreply.github.com @@ -0,0 +1 @@ +upicat diff --git a/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md b/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md index ebbc7f212f7b..a869a968d218 100644 --- a/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md +++ b/website/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md @@ -177,6 +177,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 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md index fa2f18598139..c68075a54021 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md @@ -164,6 +164,17 @@ uv run "$SCRIPT" restart-run-all --path --save-outputs --compac 8. **偶发的 websocket 超时** —— 某些操作（尤其是内核重启后）首次尝试可能超时。在上报问题前先重试一次。 +9. **如果 websocket 在此主机上持续超时**，强制使用 zmq 传输： + `uv run "$SCRIPT" execute --transport zmq ...`。症状：每次 execute 都返回 + "Websocket execution may already have reached the kernel, so auto fallback was + skipped"。内核实际上运行正常（REST 显示 execution_state=idle 且 + execution_count 递增）—— 只是 websocket 回复通道损坏。zmq 传输直接使用 + jupyter_client，可绕过此问题。 + +10. **为纯 REST 使用启动新服务器时**，添加 + `--ServerApp.disable_check_xsrf=True` —— 否则 POST /api/sessions 会返回 + `"'_xsrf' argument missing from POST"`，导致内核会话创建失败。 + ## 超时默认值 脚本每次执行的默认超时为 30 秒。对于长时间运行的操作，传入 `--timeout 120`。初始设置或大量计算时，建议使用较宽松的超时值（60 秒以上）。 \ No newline at end of file