Settings "Open configuration file" fails with a generic error on Linux hosts without xdg-open; the real error is hidden

[yuhenghuang]

Summary

On a Linux host without xdg-open (e.g. a minimal container / VS Code dev container), the Settings → General → "Open configuration file" button always fails, showing only the generic red text "Could not open configuration file". The underlying cause — the host spawns xdg-open unconditionally and it does not exist (spawn xdg-open ENOENT) — is never surfaced to the user.

Environment

• @deepseek-ai/dsh 0.1.0-rc.6 (global npm install)
• Node v24.19.0
• OS: Linux aarch64 (linuxkit container), running as a VS Code Remote-Containers dev container — no desktop environment
• Notable env: DISPLAY=:0 is set but no X server is actually running (stale socket); BROWSER is set (to a VS Code helper)

Steps to reproduce

1. Start dsh web on a Linux host where command -v xdg-open returns nothing (any bare container).
2. Open the GUI → Settings → General.
3. Click Open configuration file.

Expected behavior

On a host with no desktop opener, "open in the user's editor" must be a handoff, not a local spawn. The button should either:

• open the settings document in the user's browser (served over the web app's HTTP server and opened via $BROWSER), or
• open it in VS Code when a connected VS Code Remote session is detected (code --reuse-window <path>),

and when no handoff is possible, show a clear message that includes the resolved document path — never a generic error.

Actual behavior

A red inline alert appears: "Could not open configuration file". The real server error — path open failed: spawn xdg-open ENOENT — is never displayed.

Root cause

Three compounding issues:

1. Host: the Linux opener is hardcoded to xdg-open with no fallback. settings.openDocument resolves the document via prepareDocument() then calls openNativeTextFile, whose Linux branch unconditionally runs xdg-open <path> (dsh-host-apiproxy → native-path-opener.js, openNativePathWithIntent). There is no $EDITOR/$VISUAL fallback, no configurable opener command, and no catch — a missing binary propagates out and is wrapped by openTarget as path open failed: <message>. (Other domains do have a capability gate — agentPresets.openDocument already returns { opened: false, path } when canOpenPaths() is false.)

2. Headless detection is unreliable. canOpenNativePath() answers true on Linux whenever DISPLAY or WAYLAND_DISPLAY is set, even when the display socket is dead / no display server runs — so surfaces advertise native open on hosts where it cannot work. (The Settings button itself renders based on hasDocument, independent of this, so it is shown even on headless hosts.)

3. Client: the real error is swallowed behind a generic string. The settings header action (SettingsDocumentAction) renders the localized openDocument.error ("Could not open configuration file") whenever any error occurred, while SettingsDocumentStore.open() stores the actual server message in state.error — which the UI never renders.

Suggested fixes

On a host with no desktop opener, "open in the user's editor" cannot be a local spawn — a container cannot push a file into the user's editor directly. It must be a handoff. Two viable handoff paths, best as a ladder:

1. Serve the document and open it in the browser. The web app already runs an HTTP server — expose the settings document at a URL and open that URL with the platform browser opener. On Linux DSH already has this primitive (openInBrowser via $BROWSER, used for browser-renderable documents), and in container/VS Code setups $BROWSER is typically set to a helper that lands the tab in the user's real browser. This is the robust path: it needs no desktop and no editor handshake. (A served view is read-only by default — the Settings panel already renders the namespaces and can serve as the in-browser editor.)
2. Detect VS Code Remote and use its remote CLI. When running inside VS Code Remote (detectable via REMOTE_CONTAINERS_IPC, ~/.vscode-server, or the connection token), open the path with the remote CLI (code --reuse-window <path>) so the file opens in the user's attached VS Code window. This works only while the user's window is actually attached, so it must fall back to path 1 when attachment cannot be confirmed.

Plus the generic hygiene items:

• Fallback ladder for the Linux text-file opener: xdg-open → $VISUAL / $EDITOR → served-URL browser open → a clear error that names the document path (e.g. "no opener available on this host; the file is at "), or a copy-path affordance.
• Surface the real error message from SettingsDocumentStore in the action UI (at least truncated) instead of the generic locale string.
• Make canOpenNativePath detect a dead display (or have settings.openDocument mirror agentPresets.openDocument and return { opened: false, path } when no opener can run).

Related discussions

No existing discussion covers this specific bug (Settings → "Open configuration file" failing on a headless Linux host with spawn xdg-open ENOENT and a hidden error). Two nearby threads share the same underlying machinery and are worth linking:

• #541 — [web] "Open file" opens on the host machine and fails silently (no feedback) — the same host-native opener (host.openPath / openNativePath) failing to reach the user's editor from the web UI, with feedback swallowed by a .catch(() => {}). Different surface (tool-result file chips) and different failure mode (remote-vs-local), same design gap: web "open" gestures must be handoffs, not host-native spawns.
• #173 — produced-file 打开动作可拦截 (含补丁分支与测试) — proposes making the deliverables open action interceptable by client plugins, so clicks can be routed (e.g. to a browser view) instead of a hardcoded host opener. A compatible direction for the fix suggested here.

Notes

• The settings document itself is fine: ~/.dsh/settings.yaml exists, external edits hot-reload (chokidar watch), and Settings-panel edits persist correctly. Only the "open in editor" gesture is broken.
• Opening a file into the user's editor from inside a container is inherently a handoff: it works only while the editor is attached to the container. In this reporter's container $BROWSER points at the VS Code browser helper (so a served URL reaches the user's browser), and the VS Code remote CLI connects while a window is attached — hence the ladder above.
• Reproduction verified end-to-end: execFile("xdg-open", ["~/.dsh/settings.yaml"]) fails with spawn xdg-open ENOENT, and the client renders the generic string in response.

[skyzhao1223]

你这个判断是对的，我在 0.1.0-rc.6 的代码里确认了完整链路，问题出在"可打开"判定与实际 spawn 不一致，且错误被吞掉。

代码链路确认

• 设置面板「打开配置文件」→ 客户端 SettingsDocumentStore.open() → settings.openDocument() → Host 端 openTextFile() → openNativeTextFile()。
• 在 Linux 上，openNativePathWithIntent()（dsh-host-apiproxy 的 native-path-opener）无条件执行 run('xdg-open', [path], signal)，不检查 xdg-open 是否存在。
• 而"是否显示可打开"的判定 canOpenNativePath() 只看：isWsl || DISPLAY 存在 || WAYLAND_DISPLAY 存在。你的环境 DISPLAY=:0 虽然已设置（但 X server 没在跑），所以它返回 true，按钮被显示、点击后直接 spawn xdg-open → ENOENT。
• 错误信息在 openTarget 里被 catch 后只返回 path open failed: ...，UI 侧 open() 再兜一层，最终用户只看到通用的 "Could not open configuration file" / "无法打开配置文件"，真实原因（spawn xdg-open ENOENT）完全被隐藏。

结论

这确实是个值得修的 bug，两点都成立：

1. canOpenNativePath() 应该同时检查 xdg-open 是否在 PATH 上（Linux 非 WSL 时 command -v xdg-open），否则 headless/容器环境就不该提供"打开"按钮。
2. 打开失败的错误应该透传给用户，而不是吞成通用文案。

临时绕过

• 手动打开：配置文件路径就是 settings.yaml（默认在 ~/.dsh/settings.yaml），直接用编辑器打开即可。
• 设置 BROWSER 没用：因为该路径走的是 xdg-open 而非 $BROWSER，所以你在环境里设 BROWSER 不会生效。
• 如果一定要在无桌面容器里"打开"，可以装一个 xdg-open（或给它配一个 fallback 到 $EDITOR），让 spawn 不 ENOENT —— 但这只是绕开，根因修复还是上面两点。