image_gen: expose transport causes and retry diagnostics for images/edits network failures

What version of Codex CLI is running?

codex-cli 0.154.0 (matches the latest stable GitHub release when checked on 2026-09-14).

What subscription do you have?

Built-in Codex image generation through the ChatGPT backend. Exact subscription tier and remaining image/general usage allowance were not verified.

Which model were you using?

Agent model: GPT-6 Astra. The image model selected internally by the built-in tool was not exposed in the failure.

What platform is your computer?

macOS 26.5.1 (25F80), Apple Silicon / arm64. No filesystem sandbox restrictions in the reproducing session.

What issue are you seeing?

The built-in image_gen tool fails after several minutes with only:

image generation failed: network error: error sending request for url (https://chatgpt.com/backend-api/codex/images/edits)

No image is returned. Neither the surfaced error nor the previously inspected HTTP log exposes an HTTP status, server error code, request ID, or nested transport error. This makes it impossible to distinguish a connection/upload/response timeout from a proxy reset or a service-side problem, or to determine whether a quota/moderation error was received but hidden.

Five images had previously succeeded in an 18-image project. Subsequent reference-image requests failed repeatedly across resumed sessions. The latest run made two sequential calls for the first missing image; both failed with the exact error above and returned no new artifact. No concurrent image calls were made. This is not evidence of a five-image quota.

What steps can reproduce the bug?

Observed workflow (not yet reduced to a minimal reproducer on another network):

1. Run Codex with a local HTTP proxy configured in its environment: http://127.0.0.1:7890 (FlClash, rule mode).
2. Open two local original TV-still JPEG references using view_image; both are readable.
3. Invoke the built-in image tool with the existing full scene prompt and referenced_image_paths containing those two JPEGs only.
4. Wait for the tool to finish. It returns the generic network error above after several minutes, without an image.
5. Retry sequentially: the same failure recurs.

Prompt summary: one standalone vertical 3:4 photorealistic summer snapshot of Jia Baoyu and Shi Xiangyun from the 1987 CCTV adaptation of Dream of the Red Chamber, using the original TV stills for faces, hairstyles, makeup, costumes and accessories. On a sunny garden lawn, Xiangyun laughs while a small brightly colored toy water pistol sprays Baoyu's raised forearm; he turns and playfully shields himself. Opaque costumes, realistic anatomy, no text or watermark. This is a summary of the actual detailed prompt, not a separately tested minimal prompt.

No alternate API, image CLI, or direct authenticated replay was used.

Timing and connection evidence

An earlier instrumented reproduction on the same setup recorded five POST failures within a single tool invocation:

Failure	UTC timestamp (2026-09-13)
1	17:28:53
2	17:29:53
3	17:30:54
4	17:31:55
5	17:32:58

Three earlier complete failed tool invocations lasted 304.712, 304.604, and 304.593 seconds. The approximately 305-second total should not be interpreted as a single configured request timeout: the instrumented call shows repeated failures roughly 60 seconds apart.

nettop sampled every 5 seconds showed successive connections to the local proxy. Each sent 682,393 bytes and received approximately 4,020 bytes, then its counters stopped increasing for about a minute before a replacement connection appeared. This supports an internal retry pattern, but does not identify which layer enforces the timeout. Bytes sent to the local proxy do not prove receipt by the upstream server; received bytes may include handshake traffic.

Other observations during the earlier investigation:

• Requests from the same Codex process to /backend-api/codex/models returned HTTP 200 during the failure window.
• Proxy CONNECT and TLS verification succeeded.
• An unauthenticated empty POST to the image edits endpoint returned HTTP 401 JSON. This proves only basic route reachability, not successful authenticated multipart upload or generation.
• An unauthenticated HEAD returned a Cloudflare 403 challenge; this is not evidence that the actual authenticated POST was blocked.
• Direct access without the proxy did not connect within an 8-second diagnostic deadline. No working alternate egress was tested.

Codex doctor report

Ran codex doctor --json on 2026-09-14. Relevant check summaries (full report omitted because it contains unrelated local paths/configuration):

codexVersion: 0.154.0
auth.credentials: ok — auth is configured
installation: ok — installation looks consistent
network.env: ok — network-related environment looks readable
network.provider_reachability: ok — active provider endpoints are reachable over HTTP
network.websocket_reachability: ok — Responses WebSocket handshake succeeded

These checks do not exercise the image-generation request itself and should not be interpreted as proof that the image route is healthy.

What is the expected behavior?

Please expose enough redacted diagnostic information to make this failure actionable:

• Nested transport cause: DNS, connect, TLS, upload, read timeout, reset, etc., when available.
• Attempt number, per-attempt elapsed time, retry reason, and effective timeout; distinguish one request from the full tool invocation.
• If an HTTP response was received: status, safe structured error code, request/correlation ID, and Retry-After when available.
• Explicitly distinguish usage/quota, moderation, authentication, and transport errors when known; otherwise state that no usable HTTP response was obtained.
• Document whether the image path has a separate timeout/retry policy and whether any supported setting affects it.

Please do not include authorization headers, cookies, image payloads, or full prompts in default diagnostic output.

The root cause is still unknown. The request here is for better diagnostics, not an assertion that Codex itself, the proxy, quota enforcement, or moderation is responsible.

Related reports

• #32297: macOS built-in generation route returns a similar generic network error without reference images.
• #40233: Windows reference-image calls hang; this report instead has a bounded failure and a measured retry sequence on macOS.
• #33050: intermittent generation failures with long durations.

This issue focuses on the missing transport/error details and the observed retry pattern for /images/edits.

Start at the image_gen handling for the /backend-api/codex/images/edits request and inspect how retries and network errors are currently surfaced. Compare the implementation with the requested attempt timing, transport causes, HTTP details, and redaction rules; done means failures distinguish available transport, service, and usage information without exposing credentials, prompts, or image data.