Unauthenticated TUI reports failed embedded app server instead of login guidance

Summary

When Codex CLI is not authenticated, launching the interactive TUI can fail with:

Error: failed to start embedded app server

This is misleading because codex doctor --summary shows the real actionable problem is missing credentials:

✗ auth no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.

Environment

• Codex CLI: codex-cli 0.142.3
• Platform: linux-x86_64
• Install method: npm global package
• Terminal: VS Code terminal
• tmux: tmux 3.3a
• Auth state: no Codex credentials configured

Doctor summary excerpt:

Codex Doctor v0.142.3 · linux-x86_64

Notes
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support.

Configuration
  ✓ config       loaded
  ✗ auth         no Codex credentials were found — Run codex login or provide an API key through a supported auth env var.
  ✓ mcp          no MCP servers configured
  ✓ sandbox      restricted fs + restricted network · approval OnRequest

Background Server
  ○ app-server   not running (ephemeral mode)

Reproduction

On a Linux machine without Codex credentials configured:

REAL_CODEX=/path/to/npm-global/bin/codex
$REAL_CODEX --version
$REAL_CODEX doctor --summary

tmux new-session -s codex-debug "$REAL_CODEX; echo; echo codex-exit=\$?; echo 'press enter to close'; read"

The tmux session displays:

Error: failed to start embedded app server

codex-exit=0
press enter to close

This also happens when Codex is launched through a wrapper such as codex-hud, but the minimal reproduction above bypasses the wrapper and runs the real Codex CLI directly.

Expected behavior

If credentials are missing, the interactive CLI should report an actionable authentication error, for example:

No Codex credentials were found. Run codex login or configure an API key.

It should not primarily surface failed to start embedded app server, because that points users toward tmux/app-server debugging instead of the actual missing-auth remediation.

If startup cannot continue because authentication is missing, it should also consider returning a non-zero exit status.

Related

This may be adjacent to #30514, but that issue is about codex exec retrying 401s. This report is specifically about the interactive TUI startup path surfacing an embedded app-server error when the actionable condition is missing credentials.