›_ Codex Issues
Codex Issues / #16432

WebSocket connection fails with non-ASCII characters in workspace path

Resolved 💬 4 comments Opened Apr 1, 2026 by 7vf7gcpwsy-create Closed Apr 30, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Bug

Codex CLI fails to establish WebSocket connections when the workspace path contains non-ASCII characters (e.g., CJK characters). The path is placed into the x-codex-turn-metadata HTTP header, which does not support non-ASCII bytes.

Reproduction

# Working directory contains Chinese characters: /Users/me/大山/shipping-analysis
codex exec "echo hello"

Error

ERROR codex_api::endpoint::responses_websocket: failed to connect to websocket:
UTF-8 encoding error: failed to convert header to a str for header name
'x-codex-turn-metadata' with value: "...com~apple~CloudDocs/\xe5\xa4\xa7\xe5\xb1\xb1/shipping-analysis..."

\xe5\xa4\xa7\xe5\xb1\xb1 is valid UTF-8 for 大山, but HTTP headers are restricted to visible ASCII (RFC 7230 §3.2.6). The connection retries 5 times and eventually falls back, but this adds ~10 seconds of delay to every single invocation.

Expected behavior

Non-ASCII path components in x-codex-turn-metadata should be percent-encoded or base64-encoded before being placed into the HTTP header.

Environment

  • Codex CLI: v0.118.0
  • OS: macOS 15.4 (Darwin 25.4.0)
  • Auth: ChatGPT (Pro plan)
  • Path: iCloud Drive path containing CJK characters

Workaround attempted

Creating an ASCII-only symlink does not help — Codex resolves symlinks to the real path internally.

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 4 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #15463

Powered by Codex Action

cjahv · 4 months ago

I can reproduce the same failure on a newer Codex CLI release with a Chinese workspace path on macOS.

Environment:

  • Codex CLI: codex-cli 0.123.0
  • OS: macOS 26.4.1, build 25E253; Darwin 25.4.0 arm64
  • Locale: LANG=zh_CN.UTF-8, LC_CTYPE=C.UTF-8, LC_ALL=C.UTF-8
  • Workspace path shape: /Users/.../Documents/Projects/doc/zh/<Chinese workspace name>
  • Workspace state in metadata: has_changes: true

Observed error:

Falling back from WebSockets to HTTPS transport. stream disconnected before completion: UTF-8 encoding error: failed to convert header to a str for header name `x-codex-turn-metadata` with value: "{\"session_id\":\"...\",\"thread_source\":\"user\",\"turn_id\":\"...\",\"workspaces\":{\"/Users/.../Documents/Projects/doc/zh/<Chinese workspace name>\":{\"has_changes\":true}},\"sandbox\":\"none\"}"

The failing header value contains the workspace path encoded as escaped UTF-8 byte sequences for the Chinese path component, e.g. \\xe6.... This appears to still affect the CLI in 0.123.0, not only 0.118.0.

I am redacting the exact local project name, but the trigger is a non-ASCII/CJK workspace path being included in x-codex-turn-metadata during stream fallback/reconnect.

polaris-yamamoto · 4 months ago

Confirming this is still reproducible on codex-cli v0.125.0 (latest stable, 2026-04-30).

Environment

  • macOS 15.x (Darwin 25.4.0), arm64
  • codex-cli 0.125.0 (npm global, ChatGPT auth)
  • Workspace path contains Japanese characters (OneDrive sync directory):

/Users/<user>/Library/CloudStorage/OneDrive-ポラリスソリューションズ株式会社/Project/Claude-Almighty

Behavior

  • 5 reconnect attempts, then a fallback path eventually succeeds
  • Each invocation incurs ~7-10 seconds of delay
  • Same error signature as the original report:

failed to convert header to a str for header name 'x-codex-turn-metadata'
with value: "...workspaces":{"/Users/.../OneDrive-\xe3\x83\x9b\xe3\x82\x9a..."

User-side workarounds tested (none effective)

  • ASCII symlink + cd via the symlink: still fails — Codex resolves the

physical path internally (likely via git rev-parse --show-toplevel)

  • Forcing PWD / OLDPWD env vars to ASCII paths: ignored

The path embedded in the header is the realpath, not the logical cwd, so users
on cloud-sync directories with localized folder names (OneDrive's localized
tenant path, iCloud Drive CJK paths, etc.) cannot avoid this without abandoning
their sync setup.

Suggestion: percent-encode or base64-encode the JSON value before placing it
into the x-codex-turn-metadata HTTP header (RFC 7230 §3.2.6).

etraut-openai contributor · 4 months ago

This is fixed in https://github.com/openai/codex/pull/19620. The fix will be included in the next release.