openai/codex · error · std::io::Error

agent role `{role_name}` must define a description

Error message

agent role `{role_name}` must define a description

What it means

Error "agent role `{role_name}` must define a description" thrown in openai/codex.

Source

Thrown at codex-rs/core/src/config/agent_roles.rs:355

) -> std::io::Result<Option<String>> {
    match description.map(str::trim) {
        Some("") => Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!("{field_label} cannot be blank"),
        )),
        Some(description) => Ok(Some(description.to_string())),
        None => Ok(None),
    }
}

fn validate_required_agent_role_description(
    role_name: &str,
    description: Option<&str>,
) -> std::io::Result<()> {
    if description.is_some() {
        Ok(())
    } else {
        Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!("agent role `{role_name}` must define a description"),
        ))
    }
}

fn validate_agent_role_file_developer_instructions(
    role_file_label: &Path,
    developer_instructions: Option<&str>,
    require_present: bool,
) -> std::io::Result<()> {
    match developer_instructions.map(str::trim) {
        Some("") => Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!(
                "agent role file at {}.developer_instructions cannot be blank",
                role_file_label.display()
            ),

View on GitHub (pinned to 339751715c)

Solutions

1. Add a `description` to agent role `{role_name}`.

When it happens

Trigger: Thrown at codex-rs/core/src/config/agent_roles.rs:355 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/d679626ada295fef. Report an issue: GitHub.