codex - ✅(Solved) Fix npm codex wrapper aborts on Linux shutdown in uv__epoll_ctl_prep during app-server teardown [1 pull requests, 1 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#21339Fetched 2026-05-07 03:41:39
View on GitHub
Comments
0
Participants
1
Timeline
5
Reactions
0
Participants
Timeline (top)
labeled ×3cross-referenced ×2

On Linux, the npm-installed codex wrapper appears to abort during shutdown in Node/libuv teardown when used as the codex app-server entrypoint for a long-running service.

This does not currently look like an adapter-specific bug in the caller. In local testing, the problem reproduces when launching Codex through the npm codex wrapper, while the same service becomes stable when CODEX_CLI_BIN is pointed directly at the bundled native Codex binary.

Error Message

A long-running service starts Codex using the normal codex app-server --listen stdio:// ... flow.

Root Cause

On Linux, the npm-installed codex wrapper appears to abort during shutdown in Node/libuv teardown when used as the codex app-server entrypoint for a long-running service.

This does not currently look like an adapter-specific bug in the caller. In local testing, the problem reproduces when launching Codex through the npm codex wrapper, while the same service becomes stable when CODEX_CLI_BIN is pointed directly at the bundled native Codex binary.

Fix Action

Fixed

PR fix notes

PR #305: docs: document stable native Codex CLI usage for Linux deployments

Description (problem / solution / changelog)

摘要

围绕 #292 的收口,本 PR 只提供仓内当前可用的稳定方案文档,不展开现象对比或排查叙述。

变更内容

  • .gitignore 中忽略 corecore.*
  • README.md 中补充长期运行 Linux 部署应显式设置 native CODEX_CLI_BIN
  • docs/guide.md 中新增稳定 Linux 部署的配置步骤
  • docs/guide.md 中补充 native Codex binary 的解析命令,以及 PM2 / systemd 的最小配置示例

审查结论

  • 这批改动和 #292 的收口目标一致,重点是给出当下可执行的稳定用法
  • 文档没有引入额外封装或运行时代码改造,风险维持在最小范围
  • 当前方案直接对应长期运行 Linux supervisor 场景,表达清晰,落地成本低
  • 当前没有发现与需求目标不符的偏差、遗漏或冗余

验证

  • 已验证文档中的 native binary 解析命令可在本机解析到可执行路径
  • 已运行:uv run pytest --no-cov tests/package/test_release_distribution_contract.py tests/contracts/test_extension_contract_consistency.py -q
  • 未运行:bash ./scripts/validate_baseline.sh
    • 原因:本次仅涉及文档与 .gitignore 调整

关联

Changed files

  • .gitignore (modified, +2/-0)
  • README.md (modified, +1/-0)
  • docs/guide.md (modified, +34/-0)

Code Example

Program terminated with signal SIGABRT, Aborted.
frame 0: abort()
frame 1: uv__epoll_ctl_prep(...)
frame 2: uv__io_poll(...)
frame 3: node::tracing::Agent::~Agent()
frame 4: node::TearDownOncePerProcess()
frame 5: node::Start(int, char**)
RAW_BUFFERClick to expand / collapse

Summary

On Linux, the npm-installed codex wrapper appears to abort during shutdown in Node/libuv teardown when used as the codex app-server entrypoint for a long-running service.

This does not currently look like an adapter-specific bug in the caller. In local testing, the problem reproduces when launching Codex through the npm codex wrapper, while the same service becomes stable when CODEX_CLI_BIN is pointed directly at the bundled native Codex binary.

Environment

  • OS: Debian 13 (trixie)
  • Kernel: Linux 6.12.43
  • Node: v20.19.4
  • Codex CLI: 0.128.0
  • Install shape: npm global install of @openai/codex

Observed behavior

A long-running service starts Codex using the normal codex app-server --listen stdio:// ... flow.

When the service is restarted repeatedly, the wrapper-mode process frequently leaves a new core dump. The core is reported as the Node wrapper process, for example:

  • node .../bin/codex -c model="gpt-5.4" -c model_reasoning_effort="high" ...

GDB backtrace

A representative core shows:

Program terminated with signal SIGABRT, Aborted.
frame 0: abort()
frame 1: uv__epoll_ctl_prep(...)
frame 2: uv__io_poll(...)
frame 3: node::tracing::Agent::~Agent()
frame 4: node::TearDownOncePerProcess()
frame 5: node::Start(int, char**)

So this appears to be a wrapper/Node/libuv teardown abort, not an ordinary application-level failure inside the caller.

Reproduction comparison

I ran a controlled restart comparison against the same long-running service process.

A. Wrapper mode

The service used the default npm-installed codex wrapper.

Repeated restart result:

  • restart 1: new core dump
  • restart 2: new core dump
  • restart 3: new core dump

B. Native binary mode

The service was reconfigured to point directly at the bundled native binary instead of the npm wrapper.

Repeated restart result after native mode was active:

  • restart 1 after switching: one final core from the old wrapper process during the transition
  • restart 2: no new core dump
  • restart 3: no new core dump

This strongly suggests the instability is tied to the Node wrapper shutdown path rather than to the underlying app-server workflow itself.

Why this seems worth reporting

The current npm wrapper is the default and most discoverable entrypoint. If it can leave repeatable SIGABRT core dumps during normal service restarts, downstream integrators may see frequent crash artifacts even when the bundled native Codex binary is otherwise stable.

Expected behavior

Using the default npm-installed codex wrapper as the app-server entrypoint for a long-running service should not abort during normal restart/shutdown cycles.

Possible directions

Any of these would help:

  • fix the wrapper/Node teardown abort itself
  • document known Linux wrapper instability if this is already understood
  • provide a stable first-class way to resolve or opt into the bundled native binary without relying on internal npm package layout

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…

FAQ

Expected behavior

Using the default npm-installed codex wrapper as the app-server entrypoint for a long-running service should not abort during normal restart/shutdown cycles.

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

codex - ✅(Solved) Fix npm codex wrapper aborts on Linux shutdown in uv__epoll_ctl_prep during app-server teardown [1 pull requests, 1 participants]