{"record":{"id":"9924aa6814724dc9","repo":"openai/codex","slug":"fatal-error-0","errorCode":null,"errorMessage":"Fatal error: {0}","messagePattern":"Fatal error: (.+?)","errorType":"exception","errorClass":"CodexErr","httpStatus":null,"severity":"critical","filePath":"codex-rs/protocol/src/error.rs","lineNumber":164,"sourceCode":"    UsageNotIncluded,\n    #[error(\"We're currently experiencing high demand, which may cause temporary errors.\")]\n    InternalServerError,\n    /// Retry limit exceeded.\n    #[error(\"{0}\")]\n    RetryLimit(RetryLimitReachedError),\n    /// Agent loop died unexpectedly\n    #[error(\"internal error; agent loop died unexpectedly\")]\n    InternalAgentDied,\n    /// Sandbox error\n    #[error(\"sandbox error: {0}\")]\n    Sandbox(#[from] SandboxErr),\n    #[error(\"codex-linux-sandbox was required but not provided\")]\n    LandlockSandboxExecutableNotProvided,\n    #[error(\"unsupported operation: {0}\")]\n    UnsupportedOperation(String),\n    #[error(\"{0}\")]\n    RefreshTokenFailed(RefreshTokenFailedError),\n    #[error(\"Fatal error: {0}\")]\n    Fatal(String),\n    // -----------------------------------------------------------------\n    // Automatic conversions for common external error types\n    // -----------------------------------------------------------------\n    #[error(transparent)]\n    Io(#[from] io::Error),\n    #[error(transparent)]\n    Json(#[from] serde_json::Error),\n    #[cfg(target_os = \"linux\")]\n    #[error(transparent)]\n    LandlockRuleset(#[from] landlock::RulesetError),\n    #[cfg(target_os = \"linux\")]\n    #[error(transparent)]\n    LandlockPathFd(#[from] landlock::PathFdError),\n    #[error(transparent)]\n    TokioJoin(#[from] JoinError),\n    #[error(\"{0}\")]\n    EnvVar(EnvVarError),","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/protocol/src/error.rs#L146-L182","documentation":"CodexErrorDetails::Fatal(String) at error.rs:164-165 prints 'Fatal error: {0}' for conditions the session cannot recover from. It is non-retryable (is_retryable returns false, error.rs:370) and falls through to CodexErrorInfo::Other at the protocol boundary (error.rs:454), so hosts should stop the turn or session and surface the message instead of attempting automatic recovery.","triggerScenarios":"Constructed via CodexErr::Fatal(message) (error.rs:335) on unrecoverable internal conditions where no dedicated variant exists - for example session or rollout state that can no longer be persisted or trusted. By design it marks state you must not keep operating on.","commonSituations":"Disk-full or permission failures while writing rollout/session state escalated to fatal; resuming a truncated or corrupted rollout file; internal defects that lack a specific error variant.","solutions":["Stop the current thread or session - do not retry; the variant is non-retryable by classification.","Read the {0} payload; it names the underlying unrecoverable condition.","Check environment basics: disk space and permissions on CODEX_HOME and session storage.","Start a fresh thread; if resuming a rollout triggered it, inspect or discard that rollout file.","If reproducible, capture the payload and report via /feedback - Fatal often marks an internal defect."],"exampleFix":"// before: logging and continuing\nif let Err(e) = session.run().await {\n    log::error!(\"{e}\"); // keeps a corrupted session alive\n}\n\n// after: treat Fatal as terminal\nmatch err.details() {\n    CodexErrorDetails::Fatal(msg) => {\n        session.shutdown().await?;\n        report_and_exit(msg);\n    }\n    _ => return Err(err.into()),\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"fn is_fatal(err: &CodexErr) -> bool {\n    matches!(err.details(), CodexErrorDetails::Fatal(_))\n}","tryCatchPattern":"Err(err) if matches!(err.details(), CodexErrorDetails::Fatal(_)) => {\n    // halt the agent loop, persist nothing further, surface the message\n    halt_and_report(&err).await;\n}","preventionTips":["Keep sessions and rollouts on storage with free space and write permission.","Avoid killing the process mid-turn to prevent truncated rollout files.","Treat Fatal in logs as a signal to file a bug, not to retry."],"tags":["rust","codex","internal","unrecoverable","session"],"backgroundTag":"unrecoverable-fatal-error","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}