openai/codex · error · CodexErr

unsupported operation: {0}

Error message

unsupported operation: {0}

What it means

Variant CodexErrorDetails::UnsupportedOperation(String) in codex-rs/protocol/src/error.rs:160 rejects an operation the current Codex build, configuration, or executor cannot perform; the payload names the operation. It is non-retryable (is_retryable returns false, error.rs:377) and maps to CodexErrorInfo::BadRequest at the protocol boundary (error.rs:450-452), so treat it as a contract error, not a transient fault.

Source

Thrown at codex-rs/protocol/src/error.rs:160

    QuotaExceeded,
    #[error(
        "To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus."
    )]
    UsageNotIncluded,
    #[error("We're currently experiencing high demand, which may cause temporary errors.")]
    InternalServerError,
    /// Retry limit exceeded.
    #[error("{0}")]
    RetryLimit(RetryLimitReachedError),
    /// Agent loop died unexpectedly
    #[error("internal error; agent loop died unexpectedly")]
    InternalAgentDied,
    /// Sandbox error
    #[error("sandbox error: {0}")]
    Sandbox(#[from] SandboxErr),
    #[error("codex-linux-sandbox was required but not provided")]
    LandlockSandboxExecutableNotProvided,
    #[error("unsupported operation: {0}")]
    UnsupportedOperation(String),
    #[error("{0}")]
    RefreshTokenFailed(RefreshTokenFailedError),
    #[error("Fatal error: {0}")]
    Fatal(String),
    // -----------------------------------------------------------------
    // Automatic conversions for common external error types
    // -----------------------------------------------------------------
    #[error(transparent)]
    Io(#[from] io::Error),
    #[error(transparent)]
    Json(#[from] serde_json::Error),
    #[cfg(target_os = "linux")]
    #[error(transparent)]
    LandlockRuleset(#[from] landlock::RulesetError),
    #[cfg(target_os = "linux")]
    #[error(transparent)]
    LandlockPathFd(#[from] landlock::PathFdError),

View on GitHub (pinned to 339751715c)

Solutions

1. Read the String payload after 'unsupported operation:' - it names exactly which operation was refused.
2. Check that all components run compatible versions (update the codex crates, app-server, and TUI together) so the operation exists.
3. Enable the feature flag or configuration key the operation requires.
4. If the operation is genuinely unsupported here, branch to an alternative API instead of retrying - is_retryable is false.
5. If it should be supported, capture the payload and report it via /feedback or a GitHub issue.

Example fix

// before: retrying any failure
if run_op(&mut codex).await.is_err() {
    schedule_retry().await; // wrong: never becomes retryable
}

// after: branch on the variant and stop retrying
match err.details() {
    CodexErrorDetails::UnsupportedOperation(op) => {
        tracing::warn!("operation unsupported here: {op}");
        fallback_path().await?;
    }
    _ => return Err(err.into()),
}

fn is_unsupported_operation(err: &CodexErr) -> bool {
    matches!(err.details(), CodexErrorDetails::UnsupportedOperation(_))
}

match result {
    Ok(value) => { /* ... */ }
    Err(err) if matches!(err.details(), CodexErrorDetails::UnsupportedOperation(_)) => {
        // do not retry; surface to the user or take a fallback path
    }
    Err(err) => return Err(err),
}

When it happens

Trigger: Calling a core/app-server/protocol API for an operation unavailable in the current setup: gated behind a disabled feature flag, missing on this platform or sandbox mode, or present only in a newer protocol version than the running components. Constructed via CodexErr::UnsupportedOperation(message) (error.rs:333) and delivered in an ErrorEvent with codex_error_info = BadRequest.

Common situations: Version skew between client crates, app-server, and TUI; experimental features turned off in config.toml; platform-specific behavior differences (macOS Seatbelt vs Linux landlock); MCP or tool configurations requesting an operation the active sandbox policy refuses.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• invalid network proxy attribution frame
• pid-managed app-server shutdown is unsupported on this platf
• pid-managed updater shutdown is unsupported on this platform
• failed to read start time for pid-managed app server {pid}
• pid-managed app server {pid} has no recorded start time

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