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

agent role file at {} must define `developer_instructions`

Error message

agent role file at {} must define `developer_instructions`

What it means

Error "agent role file at {} must define `developer_instructions`" thrown in openai/codex.

Source

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

        ))
    }
}

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()
            ),
        )),
        Some(_) => Ok(()),
        None if require_present => Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            format!(
                "agent role file at {} must define `developer_instructions`",
                role_file_label.display()
            ),
        )),
        None => Ok(()),
    }
}

async fn validate_agent_role_config_file(
    fs: &dyn ExecutorFileSystem,
    role_name: &str,
    config_file: Option<&AbsolutePathBuf>,
) -> std::io::Result<()> {
    let Some(config_file) = config_file else {
        return Ok(());
    };

View on GitHub (pinned to 339751715c)

Solutions

1. Add a `developer_instructions` field to the agent role file.

When it happens

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