Skip to content

fix(terminal): prevent crash in headless/Docker environments (#108) - #110

Merged
Lexus2016 merged 1 commit into
mainfrom
fix/terminal-headless-crash
Sep 20, 2026
Merged

Lexus2016 merged 1 commit into
mainfrom
fix/terminal-headless-crash

Conversation

@Lexus2016

Copy link
Copy Markdown
Owner

Closes #108

Summary

When attempting to open a graphical terminal or delegate in a headless Linux / Docker environment, Claude Code Studio threw an uncaughtException:

Error: Executable not found in $PATH: "gnome-terminal"
    at spawn
    at openTerminal (/app/server.js:10865:9)

Root Cause

  1. In Node.js, child_process.spawn returns a ChildProcess synchronously without throwing. The surrounding try/catch blocks in openTerminal and /api/sessions/:id/open-terminal never caught missing executables; instead, an unhandled error event was emitted on the child process, triggering an uncaughtException.
  2. In Docker and headless Linux environments, neither $DISPLAY nor $WAYLAND_DISPLAY is present, making graphical terminal emulators unusable.

Changes

  • Added isHeadless() and hasCommand() helper functions in delegate-terminal.js.
  • openTerminal: guards against headless environments on Linux and checks command existence with hasCommand() before spawning.
  • Added p.on('error', ...) listener to spawned processes to prevent unhandled ENOENT exceptions.
  • /api/sessions/:id/open-terminal: guards against headless environments and safely returns { ok: false, command: fullCmd }, allowing the frontend to copy the command to clipboard.
  • Added unit tests in test/delegate-terminal.test.js covering headless detection, command presence checks, and terminal candidate configurations.

@Lexus2016
Lexus2016 merged commit 8be10a2 into main Sep 20, 2026
2 checks passed
@Lexus2016
Lexus2016 deleted the fix/terminal-headless-crash branch September 20, 2026 19:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug: Application Crashes When Opening Terminal in Docker Environment

1 participant