Codex CLI stderr decoded as strict UTF-8 raises UnicodeDecodeError instead of RuntimeError on non-UTF-8 Windows

[ppcvote]

Please read this first

• Have you read the docs? Yes
• Have you searched for related issues? Yes. fix: handle non-UTF8 Codex stderr #4480 proposed the fix below and was closed for lack of a real Codex CLI reproduction; this issue is that reproduction.

Describe the bug

CodexExec.run decodes the Codex CLI's stderr as strict UTF-8 (src/agents/extensions/experimental/codex/exec.py:207). On Windows with a non-UTF-8 code page, when the npm-installed codex.CMD shim fails, cmd.exe writes its error in that code page, so the SDK raises UnicodeDecodeError instead of RuntimeError: Codex exec exited with code 1: ..., and both the exit code and the message are lost.

When #4480 was closed, the request was: "please provide the OS, Codex CLI version, invocation or configuration, and a reproduction or captured stderr byte sequence with secrets removed."

• OS: Windows 10 (10.0.19045), Traditional Chinese, ANSI and OEM code page 950
• Codex CLI: 0.157.1 from npm install @openai/codex, resolved by find_codex_path() to node_modules\.bin\codex.CMD
• Invocation: Codex(env={"CODEX_API_KEY": ...}). env replaces the CLI process environment (codex_options.py: "do not inherit os.environ"), so Node.js is not on its PATH and the shim fails before Codex starts. A PATH of only C:\Windows\System32, as a service account might have, gives the same result.
• Captured stderr (exit code 1):

b'\'"node"\' \xa4\xa3\xacO\xa4\xba\xb3\xa1\xa9\xce\xa5~\xb3\xa1\xa9R\xa5O\xa1B\xa5i\xb0\xf5\xa6\xe6\xaa\xba\xb5{\xa6\xa1\xa9\xce\xa7\xe5\xa6\xb8\xc0\xc9\xa1C\r\n'

That is cp950 for '"node"' 不是內部或外部命令、可執行的程式或批次檔。, the localized form of "'node' is not recognized as an internal or external command, operable program or batch file." On an English system the same message is ASCII, so it decodes.

With the one-line change from #4480, .decode("utf-8", errors="replace"), the same run raises RuntimeError: Codex exec exited with code 1: '"node"' ... with the exit code and "node" intact. That is also how the rest of the SDK decodes subprocess output: src/ has 57 .decode("utf-8", errors="replace") calls, including the Docker sandbox's stdout and stderr (src/agents/sandbox/sandboxes/docker.py:560-561). If you want the text itself as well, .decode("oem") recovers it in full on this machine, as a Windows-only fallback.

Debug information

• Agents SDK version: 0.22.3 from PyPI, and main at 588826c
• Python version: 3.11.6
• Operating system: Windows 10 (10.0.19045), code page 950
• Model and model provider: not reached; the CLI fails before any request
• Does the issue reproduce with the latest Agents SDK release? Yes, 0.22.3
• Does the issue occur consistently or intermittently? Consistently

  File "...\agents\extensions\experimental\codex\exec.py", line 207, in run
    stderr_text = b"".join(stderr_chunks).decode("utf-8")
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xa4 in position 9: invalid start byte

Repro steps

With codex from npm install @openai/codex on PATH, on Windows with a non-UTF-8 code page:

import asyncio

from agents.extensions.experimental.codex import Codex


async def main():
    # `env` replaces os.environ for the Codex CLI process, so Node.js is not on its PATH
    # and the npm shim fails; cmd.exe reports that in the console code page.
    codex = Codex(env={"CODEX_API_KEY": "sk-test-not-a-real-key"})
    thread = codex.start_thread({"skip_git_repo_check": True})
    await thread.run("say hi")


asyncio.run(main())

Expected behavior

RuntimeError: Codex exec exited with code 1: ... with the CLI's message, as on an English system.

Investigated and written by Claude Code, which also ran the reproduction on my machine.

[KHG420]

Thanks for providing the captured stderr bytes and Windows reproduction. The CLI's nonzero-exit handling currently decodes stderr as strict UTF-8, so the decoding error masks the intended RuntimeError. Decoding with errors="replace" preserves the exit code and readable parts of the stderr (such as "node") even when the localized bytes are not UTF-8, consistent with other subprocess handling in the SDK.

I implemented this small fix with a regression test in my fork: KHG420#1. Its GitHub Actions Tests workflow passed all 18 jobs.

I understand the repository currently limits pull requests to collaborators. If the maintainers are able to accept an upstream PR for this fix, I would be honored to submit it.

[jbeckwith-oai]

Thank you for following up with such a detailed report! The Windows environment details and captured CP950 stderr provided the concrete reproduction we were missing in #4480 and made it possible to confirm the failure. Thanks also to @KHG420 for investigating and preparing a fix.

This is fixed on main by #5186, with regression coverage for both Thread.run() and Thread.run_streamed(). Non-UTF-8 stderr now produces the intended RuntimeError with the subprocess exit code and readable diagnostic text; undecodable bytes become replacement characters, while valid UTF-8 diagnostics remain intact.

The issue is closed as resolved. The fix is not yet in the latest published release, v0.22.3, and is on main for the next release. We appreciate the careful reproduction and everyone’s help getting this addressed!