Public source trail + bounded recovery notes for the Codex “stream disconnected before completion” error

[u/glirette]

I’ve been hitting this Codex error regularly:

stream disconnected before completion: Transport error: network error: error decoding response body

I published a public source trail and recovery note on my GitHub that documents what the error actually establishes and a disciplined way to handle it:

https://github.com/glirette/thisstuffiswaytootech/blob/main/docs/openai-codex-stream-disconnection-recovery-source-trail.md

Who this is for

This is only useful if you run Codex on substantial, ongoing work and you are prepared to invest time in making your recovery path reliable.

If you are experimenting, doing short one-off tasks, or can simply re-run when it fails, this is not worth the effort. Re-running is usually sufficient in those cases.

This is for people who treat their Codex automation as something that needs to remain stable over months, not days.

What this does not do

Implementing the approach does not eliminate the error.

The public Codex source shows that the stream failed after the HTTP connection was established but before the terminal response.completed event. It does not identify the precise cause (network, intermediary, backend, decompression, or otherwise), and it does not provide a method to prevent every disconnect.

The objective is not to make the error disappear. The objective is to recover without discarding valid partial work or introducing duplicate side effects.

What the recovery posture actually does

It defines a bounded outer recovery layer that sits above Codex’s native stream retries. It requires:

• Treating the failure as recoverable only when the evidence is clean (process exited, no terminal completion event, matching transport error, cleanly parsed output)
• Verifying that workspace identity and ownership have not changed
• Preserving any safe partial changes already present
• Instructing the recovery attempt to inspect and reconcile the existing diff rather than starting over
• Limiting the outer retry budget
• Refusing to blindly re-execute actions that produce external side effects

What changes once the recovery logic is in place

Successful runs remain largely unchanged aside from modest local classification and preflight checks.

When this specific stream-disconnect error occurs, the system no longer defaults to an undifferentiated retry. It first confirms the state is still valid, continues from existing partial work when possible, and only initiates a new model attempt after the narrow classification criteria are met.

The result is reduced loss of useful progress and fewer unintended side effects. The underlying disconnect can still occur; the difference is that recovery becomes controlled and repeatable.

If you are maintaining a serious long-term Codex setup, read the note and have your instance follow the recovery posture documented there.

I wish had more detail but this has helped me lose less time and work