TypeScript SDK Thread.run() treats fatal stream errors as successful empty turns
What issue are you seeing?
The TypeScript SDK defines a top-level fatal stream error event, but Thread.run() does not handle it.
ThreadErrorEvent is defined in sdk/typescript/src/events.ts as:
export type ThreadErrorEvent = {
type: "error";
message: string;
};
and it is included in the ThreadEvent union.
However, Thread.run() in sdk/typescript/src/thread.ts only handles:
item.completedturn.completedturn.failed
It does not handle event.type === "error".
As a result, if the underlying CodexExec.run() stream emits a fatal top-level error event, Thread.run() resolves successfully with an empty turn instead of rejecting.
Observed result from a focused local regression test:
{
"items": [],
"finalResponse": "",
"usage": null
}
This can make SDK callers interpret a fatal stream failure as a successful empty response.
What steps can reproduce the bug?
Using current openai/codex main at 155c04ad4, add a focused Jest test that stubs CodexExec.run() to emit a top-level error event:
import { Thread } from "../src/thread";
it("throws on fatal top-level stream errors", async () => {
const exec = {
async *run() {
yield JSON.stringify({ type: "error", message: "fatal stream error" });
},
};
const thread = new Thread(exec as never, {}, {});
await expect(thread.run("fail")).rejects.toThrow("fatal stream error");
});
Then run:
corepack pnpm --filter @openai/codex-sdk exec jest tests/run.test.ts -t "fatal top-level" --runInBand
Current result:
Received promise resolved instead of rejected
Resolved to value: {"finalResponse": "", "items": [], "usage": null}
What is the expected behavior?
Thread.run() should reject when it receives a fatal top-level stream error event.
A narrow fix would be to handle event.type === "error" in sdk/typescript/src/thread.ts, for example by throwing new Error(event.message), and add regression coverage for this case.
Additional information
I searched existing issues and PRs for Thread.run, runStreamed, ThreadErrorEvent, top-level stream errors, and TypeScript SDK stream error handling, and did not find an exact duplicate.
This is separate from normal turn.failed handling. The issue is specifically that the SDK event union already includes a top-level ThreadErrorEvent, but the buffered Thread.run() API ignores it.
2 Comments
I prepared a narrow fix and regression test in my fork here:
https://github.com/chanwooyang1/codex/tree/fix/thread-run-top-level-errors
This branch is rebased on the latest
openai/codexmain as of May 16, 2026.Summary:
event.type === "error"inThread.run()by throwingnew Error(event.message)CodexExec.run()to emit{ type: "error", message: "fatal stream error" }Validation:
corepack pnpm --filter @openai/codex-sdk exec jest tests/run.test.ts -t "top-level stream errors" --runInBandcorepack pnpm --filter @openai/codex-sdk lintcorepack pnpm --filter @openai/codex-sdk formatcorepack pnpm --filter @openai/codex-sdk buildI also attempted the full SDK Jest suite, but my local checkout did not have
codex-rs/target/debug/codex; building that binary failed locally inwebrtc-sysC++ compilation, so I could not complete the full-suite run on this machine.If this direction looks right, I’d be happy to open a PR if invited, following the repo’s contribution policy.
Related TypeScript SDK stream-handling issue with a small candidate patch: #23131
Different failure mode, but same area of code (
sdk/typescript/src/thread.ts): in #23131 the streamed event fails before callers receive a parsedThreadEventbecause a large MCPitem.completedpayload can be split inside a JSON string. I added a bounded-buffer parser patch and regression test there.Linking in case maintainers batch SDK stream robustness fixes together.