codex - ✅(Solved) Fix WebSocket fails with non-ASCII workspace paths (UTF-8 in x-codex-turn-metadata header) [1 pull requests, 2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openai/codex#19581Fetched 2026-04-26 05:14:30
View on GitHub
Comments
2
Participants
3
Timeline
8
Reactions
0
Author
Timeline (top)
labeled ×4commented ×2closed ×1cross-referenced ×1

Codex CLI fails to establish WebSocket connection when the workspace path contains non-ASCII Unicode characters (specifically tested with Turkish characters: ı, ğ, ş). The HTTP header x-codex-turn-metadata requires ASCII-only values per RFC 7230, but the workspace path is included unencoded in the workspaces field of the JSON metadata.

Error Message

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: "{"session_id":"...","thread_source":"user", "turn_id":"...","workspaces":{"/Users/kamer/Agentlar\xc4\xb1m":{...}}, "sandbox":"seatbelt"}" url: wss://chatgpt.com/backend-api/codex/responses

Root Cause

Codex CLI fails to establish WebSocket connection when the workspace path contains non-ASCII Unicode characters (specifically tested with Turkish characters: ı, ğ, ş). The HTTP header x-codex-turn-metadata requires ASCII-only values per RFC 7230, but the workspace path is included unencoded in the workspaces field of the JSON metadata.

Fix Action

Workaround

Run Codex outside the affected workspace:

cd /tmp && codex exec --skip-git-repo-check

This avoids triggering git workspace discovery which embeds the path in the WebSocket header.

PR fix notes

PR #19620: Escape turn metadata headers as ASCII JSON

Description (problem / solution / changelog)

Why

x-codex-turn-metadata is sent as an HTTP/WebSocket header, but Codex was serializing the metadata JSON with raw UTF-8 string contents. When a workspace path contains non-ASCII characters, common HTTP stacks can reject or corrupt that header before the request reaches the provider.

Fixes #17468. Also addresses the duplicate WebSocket report in #19581.

What changed

  • Added codex_utils_string::to_ascii_json_string, a shared helper that serializes JSON normally while escaping non-ASCII string content as \uXXXX.
  • Switched turn metadata header serialization, including merged Responses API client metadata, to use the ASCII-safe JSON helper.
  • Added coverage for non-ASCII workspace paths and non-ASCII client metadata while preserving the same parsed JSON values.

Verification

  • cargo test -p codex-utils-string
  • cargo test -p codex-core turn_metadata
  • just bazel-lock-check

Changed files

  • codex-rs/Cargo.lock (modified, +2/-1)
  • codex-rs/core/src/turn_metadata.rs (modified, +3/-2)
  • codex-rs/core/src/turn_metadata_tests.rs (modified, +15/-1)
  • codex-rs/utils/string/Cargo.toml (modified, +2/-0)
  • codex-rs/utils/string/src/json.rs (added, +85/-0)
  • codex-rs/utils/string/src/lib.rs (modified, +2/-0)

Code Example

# Setup: directory with Turkish characters
mkdir ~/Agentlarım && cd ~/Agentlarım
git init && git commit --allow-empty -m "test"

# Trigger
echo "hello" | codex exec -

# Expected: response from Codex
# Actual: 5x reconnect attempts, fallback succeeds but slow

---

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: "{\"session_id\":\"...\",\"thread_source\":\"user\",
\"turn_id\":\"...\",\"workspaces\":{\"/Users/kamer/Agentlar\xc4\xb1m\":{...}},
\"sandbox\":\"seatbelt\"}"
url: wss://chatgpt.com/backend-api/codex/responses

---

cd /tmp && codex exec --skip-git-repo-check
RAW_BUFFERClick to expand / collapse

Codex CLI UTF-8 Path Bug — Bug Report Draft

Bug version: codex-cli 0.125.0-alpha.3 Date discovered: 2026-04-25 Reproducer: Kamer ([email protected])

Summary

Codex CLI fails to establish WebSocket connection when the workspace path contains non-ASCII Unicode characters (specifically tested with Turkish characters: ı, ğ, ş). The HTTP header x-codex-turn-metadata requires ASCII-only values per RFC 7230, but the workspace path is included unencoded in the workspaces field of the JSON metadata.

Reproduction

# Setup: directory with Turkish characters
mkdir ~/Agentlarım && cd ~/Agentlarım
git init && git commit --allow-empty -m "test"

# Trigger
echo "hello" | codex exec -

# Expected: response from Codex
# Actual: 5x reconnect attempts, fallback succeeds but slow

Error Output

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: "{\"session_id\":\"...\",\"thread_source\":\"user\",
\"turn_id\":\"...\",\"workspaces\":{\"/Users/kamer/Agentlar\xc4\xb1m\":{...}},
\"sandbox\":\"seatbelt\"}"
url: wss://chatgpt.com/backend-api/codex/responses

The \xc4\xb1 is the UTF-8 byte sequence for ı (U+0131 LATIN SMALL LETTER DOTLESS I).

Workaround

Run Codex outside the affected workspace:

cd /tmp && codex exec --skip-git-repo-check

This avoids triggering git workspace discovery which embeds the path in the WebSocket header.

Suggested Fix

In the x-codex-turn-metadata header serialization code, percent-encode the workspace path values per RFC 3986, or use a separate header that supports UTF-8 (e.g., x-codex-turn-metadata-b64 with base64-encoded JSON).

Alternative: use a body field or HTTP/2 trailer instead of a header for binary-safe metadata.

Impact

  • Affects all users with non-ASCII characters in workspace paths
  • Common in non-English locales (Turkish, German, French, Japanese, Chinese, etc.)
  • WebSocket connection fails; Codex falls back to HTTP polling (slower, less efficient)
  • Each turn includes 5x reconnect retry overhead

Repository

OpenAI Codex CLI: https://github.com/openai/codex (or wherever issue tracker is)

Status

  • Issue submitted to GitHub
  • Workaround documented in araclar/codex.sh ✅ (Kamer's system)
  • Fix verified on patched version

extent analysis

TL;DR

The issue can be mitigated by percent-encoding the workspace path values in the x-codex-turn-metadata header or using a separate header that supports UTF-8.

Guidance

  • Verify the issue by checking if the workspace path contains non-ASCII Unicode characters and if the x-codex-turn-metadata header is being set correctly.
  • Use the provided workaround by running Codex outside the affected workspace with cd /tmp && codex exec --skip-git-repo-check to avoid triggering git workspace discovery.
  • Consider using a separate header that supports UTF-8, such as x-codex-turn-metadata-b64 with base64-encoded JSON, to avoid encoding issues.
  • Test the fix by creating a workspace with non-ASCII characters and verifying that the WebSocket connection is established successfully.

Example

No code snippet is provided as the issue is related to the Codex CLI and its interaction with the WebSocket connection.

Notes

The issue affects all users with non-ASCII characters in workspace paths, which is common in non-English locales. The workaround provided avoids the issue but may not be a permanent solution. A proper fix would require changes to the x-codex-turn-metadata header serialization code.

Recommendation

Apply the workaround by running Codex outside the affected workspace until a patched version is available, as it provides a temporary solution to the issue.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING