›_ Codex Issues
Codex Issues / #30519

Unauthenticated TUI reports failed embedded app server instead of login guidance

Open 💬 3 comments Opened Jun 29, 2026 by Excelius-Wang

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.

View original on GitHub ↗

3 Comments

Excelius-Wang · 2 months ago

I pushed a proposed fix branch here: https://github.com/Excelius-Wang/codex/tree/codex/embedded-auth-startup-guidance

Commit: https://github.com/Excelius-Wang/codex/commit/9879bfc609a7c1c3dd6b937489f8e9452f7e2c3b

Upstream compare link: https://github.com/openai/codex/compare/main...Excelius-Wang:codex/embedded-auth-startup-guidance?expand=1

Validation run locally:

  • just fmt
  • just test -p codex-tui embedded_app_server_auth_failure_has_login_guidance embedded_app_server_start_failure_is_returned

I could push the fork branch, but GitHub rejected API PR creation from this token/integration with CreatePullRequest permission errors, so the compare link is the next step for opening the PR.

wgu9 · 2 months ago

I confirmed the related codex exec empty-home path in #30514 on @openai/codex@0.142.3: login status and doctor both detect no credentials locally, but exec continues into Responses transport and 401 retries once the trust gate is bypassed.

For this TUI issue, the useful split may be:

  • startup should preserve the app-server startup context for real app-server failures
  • if embedded app-server startup failed because auth state is NotAuthenticated / no credentials, the TUI should surface login guidance first
  • tests should cover both paths: one auth-specific failure and one generic embedded app-server failure

I saw the proposed branch above already covers this direction, so I would avoid opening a parallel PR. The main thing to keep aligned with #30514 is that local/OSS/custom-provider no-auth paths should not be treated as first-party OpenAI auth failures.

Excelius-Wang · 1 month ago

Update after more debugging: my original repro was not caused by codex-hud and, after re-login, it also no longer looks like a missing-auth failure.

I uninstalled codex-hud, logged in again, and codex doctor on @openai/codex@0.142.3 reported auth/websocket/state as OK. The more useful minimal repro was:

codex app-server --listen off

which printed the bubblewrap warning and then failed with:

Error: Function not implemented (os error 38)

I later found that this machine had Codex installed under a NAS/network filesystem path (/mnt/bn/arnold-recommend/...), including the npm global install / Codex runtime resources / CODEX_HOME. That appears to be the root cause for my specific TUI startup failure: the embedded app-server/sandbox startup path is sensitive to filesystem/runtime features that are not reliably available from that NAS-mounted install location.

So for this issue, I would narrow my original report:

  • this specific repro should be treated as a generic embedded app-server startup failure, not as an auth failure;
  • the CLI/TUI still has a UX bug because it only surfaced failed to start embedded app server and hid the actionable lower-level context (os error 38, bubblewrap/sandbox startup path, install/runtime location);
  • auth-specific login guidance should still be handled separately, but only when the active first-party provider requires OpenAI/Codex auth and credentials are actually missing;
  • local/OSS/custom-provider no-auth paths should not be treated as first-party OpenAI auth failures, matching the #30514 boundary.

Given this new information, the proposed branch I linked above is directionally useful for the auth-specific path, but it should not be presented as a complete fix for my concrete repro unless it also improves generic app-server startup error surfacing.