openai/codex · error · CloudConfigBundleLoadError

{message}

Error message

{message}

What it means

Carrier error for a failed load of the enterprise-managed cloud config bundle. The displayed text is whatever message the backing getter produced (#[error("{message}")]); the actionable structure is the private code field - Auth, Timeout, RequestFailed, InvalidBundle or Internal - plus an optional HTTP status_code, exposed through .code() and .status_code(). Constructed by the future passed to CloudConfigBundleLoader and surfaced via CloudConfigBundleLoader::get().

Source

Thrown at codex-rs/config/src/cloud_config_bundle.rs:149

        Ok(Self {
            enterprise_managed_config,
            enterprise_managed_requirements,
        })
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CloudConfigBundleLoadErrorCode {
    Auth,
    Timeout,
    RequestFailed,
    InvalidBundle,
    Internal,
}

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("{message}")]
pub struct CloudConfigBundleLoadError {
    code: CloudConfigBundleLoadErrorCode,
    message: String,
    status_code: Option<u16>,
}

impl CloudConfigBundleLoadError {
    pub fn new(
        code: CloudConfigBundleLoadErrorCode,
        status_code: Option<u16>,
        message: impl Into<String>,
    ) -> Self {
        Self {
            code,
            message: message.into(),
            status_code,
        }
    }

View on GitHub (pinned to 339751715c)

Solutions

1. Branch on .code(): Auth means re-authenticate (re-run login) and retry the load
2. Timeout or RequestFailed means check network, proxy and egress to the config backend, then retry with backoff
3. InvalidBundle means compare client and backend versions, update the client, and verify the payload the backend serves
4. Internal means capture message and status_code and report it; retrying is unlikely to help

Example fix

// before
let bundle = loader.get().await?; // opaque error

// after: route on the structured code
let bundle = match loader.get().await {
    Ok(b) => b,
    Err(e) if e.code() == CloudConfigBundleLoadErrorCode::Auth => relogin_and_retry().await?,
    Err(e) if matches!(e.code(), CloudConfigBundleLoadErrorCode::Timeout | CloudConfigBundleLoadErrorCode::RequestFailed) => retry_with_backoff().await?,
    Err(e) => return Err(e.into()),
};

pub fn as_cloud_config_bundle_load_error(
    err: &anyhow::Error,
) -> Option<&CloudConfigBundleLoadError> {
    err.downcast_ref::<CloudConfigBundleLoadError>()
}

match loader.get().await {
    Ok(bundle) => { /* apply layers */ }
    Err(e) => match e.code() {
        CloudConfigBundleLoadErrorCode::Auth => { /* refresh credentials, retry once */ }
        CloudConfigBundleLoadErrorCode::Timeout | CloudConfigBundleLoadErrorCode::RequestFailed => { /* backoff and retry with capped attempts */ }
        CloudConfigBundleLoadErrorCode::InvalidBundle | CloudConfigBundleLoadErrorCode::Internal => { /* surface e.message() and status_code; do not retry */ }
    }
}

When it happens

Trigger: Calling (or awaiting the shared future of) CloudConfigBundleLoader::get() when the backend fetch fails: expired or invalid auth token (Auth, typically 401/403), request timeout, transport failure or 5xx (RequestFailed), a response that is not a valid bundle payload (InvalidBundle), or an unexpected client-side fault (Internal).

Common situations: Long-lived session whose SSO token expired before a config refresh; corporate proxy or egress rules blocking the config backend; a backend deploy shipping a malformed bundle; client/backend version skew.

Related errors

• failed to parse cloud config fragment {fragment}: {message}
• Environment variable {env_var} for MCP server '{server_name}
• executor-owned MCP server `{server_name}` cannot use hosted
• Environment variable {env_var} for MCP server '{server_name}
• Invalid MCP server name '{server_name}': must match pattern

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