Skip to content

fix: explain Codex config load errors caused by a deleted working directory - #626

Merged
EugeneTheDev merged 1 commit into
mainfrom
eugenethedev/human-readable-errors
Oct 13, 2026
Merged

EugeneTheDev merged 1 commit into
mainfrom
eugenethedev/human-readable-errors

Conversation

@EugeneTheDev

@EugeneTheDev EugeneTheDev commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

When the agent's working directory is deleted while it runs, Codex fails every config load with a generic message (IJAI-2923, IJAI-3685):

  • config/read → -32603 failed to resolve feature override precedence: No such file or directory (os error 2)
  • thread/start → -32600 failed to load configuration: No such file or directory (os error 2)

Codex loads project config from its process working directory, which it inherits from codex-acp, so the error says nothing about the real cause.

Change

New src/CodexErrorExplanations.ts: a single list of rules that every app-server request error goes through in CodexAppServerClient.sendRequest. A rule only rewrites the message; the error class, code and data stay, so CodexThreadErrors and app-server recovery work as before.

  • Deleted working directory: the agent records its working directory at start and checks whether the process still points at the directory at that path (a directory recreated at the same path counts as deleted). The message becomes:
    Codex cannot read its configuration: its working directory <path> was deleted or replaced after the agent started. Restart the agent.
  • Config files hint: moved here from CodexAcpServer.handleError, so it now applies to every request that fails to load config, not only session new/fork. "feature override precedence" is reworded to "failed to load configuration". Errors that require logout are skipped. handleError keeps only the logout action, via requiresLogout() from the module.

Wire shape note

Session new/fork config errors previously reached the client as data: "<message>\n\nCheck…" (a string, because the text was passed as the data argument of RequestError.internalError). They now take the SDK's default path like every other internal error: data: {details: "<message>\n\nCheck…"}. The logout error keeps its string data.

…ectory

Codex reports any config load failure of `config/read` as the generic
"failed to resolve feature override precedence". When the working directory
of the agent is deleted while it runs, every config load fails with a bare
"No such file or directory" (IJAI-2923).

Add CodexErrorExplanations, which every app-server request error passes
through in CodexAppServerClient.sendRequest:
- a deleted or replaced working directory is named, with a hint to restart;
- the config-file hint moves here from CodexAcpServer.handleError, so it
  applies to every request; handleError keeps only the logout action.

IJAI-3685
@EugeneTheDev
EugeneTheDev merged commit a636804 into main Oct 13, 2026
7 checks passed
@EugeneTheDev
EugeneTheDev deleted the eugenethedev/human-readable-errors branch October 13, 2026 16:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant