openai/codex · error · RemoteControlServerRequestError

remote control failed at ` `: HTTP , , body

Error message

remote control {response_kind} failed at `{url}`: HTTP {status}, {headers_str}, body: {body_preview}

What it means

Constructs an io::Error from RemoteControlServerRequestError::io_error after a remote-control backend HTTP request (enroll, refresh, pair, etc.) returned a non-success response. The message records the operation kind, URL, HTTP status, response headers, and a body preview. The mapped ErrorKind carries semantics: UNAUTHORIZED/FORBIDDEN -> PermissionDenied, NOT_FOUND -> NotFound, timeout without client error -> TimedOut, otherwise InvalidInput/other.

Solutions

1. Inspect the embedded HTTP status: 401/403 means re-authenticate (re-login / refresh auth) before retrying
2. 4xx other than auth means the request payload or URL is wrong — fix the caller; 5xx or timeouts can be retried with backoff honoring any retry-at header

When it happens

Trigger: Thrown at codex-rs/app-server-transport/src/transport/remote_control/server_api.rs:51 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/2199d0482c63d906. Report an issue: GitHub.

Appendix: source

Thrown at codex-rs/app-server-transport/src/transport/remote_control/server_api.rs:51

    status: Option<StatusCode>,
    retry_at: Option<OffsetDateTime>,
}

impl RemoteControlServerRequestError {
    fn io_error(
        message: String,
        status: Option<StatusCode>,
        retry_at: Option<OffsetDateTime>,
        timed_out: bool,
    ) -> io::Error {
        let kind = match status {
            Some(StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN) => ErrorKind::PermissionDenied,
            Some(StatusCode::NOT_FOUND) => ErrorKind::NotFound,
            Some(status) if timed_out && !status.is_client_error() => ErrorKind::TimedOut,
            None if timed_out => ErrorKind::TimedOut,
            Some(_) | None => ErrorKind::Other,
        };
        io::Error::new(
            kind,
            Self {
                message,
                status,
                retry_at,
            },
        )
    }

    fn is_transient(&self, kind: ErrorKind) -> bool {
        kind == ErrorKind::TimedOut
            || self.status.is_none()
            || self.status.is_some_and(|status| {
                status == StatusCode::TOO_MANY_REQUESTS || status.is_server_error()
            })
    }
}

View on GitHub (pinned to 339751715c)