openai/codex · error · io::Error

remote control client list requires environmentId

Error message

remote control client list requires environmentId

What it means

list_remote_control_clients rejects RemoteControlClientsListParams.environment_id when it is an empty string, failing fast with InvalidInput before building the environments/{id}/clients URL. The environment id scopes the client list to one remote-control environment, so an empty value has no valid server-side interpretation.

Source

Thrown at codex-rs/app-server-transport/src/transport/remote_control/clients.rs:75

    },
    Revoke {
        url: &'a Url,
    },
}

struct ClientManagementResponse {
    status: axum::http::StatusCode,
    headers: HeaderMap,
    body: Vec<u8>,
}

pub(super) async fn list_remote_control_clients(
    remote_control_url: &str,
    auth_manager: &Arc<AuthManager>,
    params: RemoteControlClientsListParams,
) -> io::Result<RemoteControlClientsListResponse> {
    if params.environment_id.is_empty() {
        return Err(io::Error::new(
            ErrorKind::InvalidInput,
            "remote control client list requires environmentId",
        ));
    }
    if params
        .limit
        .is_some_and(|limit| !(1..=100).contains(&limit))
    {
        return Err(io::Error::new(
            ErrorKind::InvalidInput,
            "remote control client list limit must be between 1 and 100",
        ));
    }
    let url = environment_clients_url(remote_control_url, &params.environment_id)?;
    let response = send_client_management_request(
        auth_manager,
        ClientManagementRequest::List {
            url: &url,

View on GitHub (pinned to 339751715c)

Solutions

1. Supply the environmentId returned by the pairing/enrollment flow (pairing status response)
2. Queue or skip the list call client-side until an environment id is known
3. If your JSON payload genuinely lacks the field, fix the producer — the v2 API requires it non-empty

Example fix

// before
let params = RemoteControlClientsListParams {
    environment_id: String::new(),
    ..Default::default()
};
list_remote_control_clients(url, &auth_manager, params).await
// Err: remote control client list requires environmentId

// after
let params = RemoteControlClientsListParams {
    environment_id: environment_id.clone(),
    ..Default::default()
};
list_remote_control_clients(url, &auth_manager, params).await  // Ok

fn can_list_clients(p: &RemoteControlClientsListParams) -> bool {
    !p.environment_id.is_empty()
}

function hasEnvironmentId(p: RemoteControlClientsListParams): p is RemoteControlClientsListParams & { environmentId: string } {
  return typeof p.environmentId === 'string' && p.environmentId.length > 0;
}

When it happens

Trigger: Calling the remote-control client list with environment_id defaulted or blank — String::new() in Rust default-struct initialization, a JSON request that sent {"environmentId": ""}, or listing before the environment id was obtained from the pairing/enrollment flow.

Common situations: TS/JSON clients that model environmentId as optional and serialize the empty string; racing the list call before pairing status delivered the environment id; Rust callers filling params with ..Default::default() and forgetting the field.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• remote control client revoke requires environmentId
• remote control client revoke requires clientId
• remote control client list limit must be between 1 and 100
• invalid remote control account id header: {err}
• remote control URL cannot be a base

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