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

agent role file at {} must contain a TOML table

Error message

agent role file at {} must contain a TOML table

What it means

Error "agent role file at {} must contain a TOML table" thrown in openai/codex.

Source

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

                std::io::ErrorKind::InvalidInput,
                format!(
                    "agent role file at {} must define a non-empty `name`",
                    role_file_label.display()
                ),
            )
        })?;

    let nickname_candidates = normalize_agent_role_nickname_candidates(
        &format!(
            "agent role file {}.nickname_candidates",
            role_file_label.display()
        ),
        parsed.nickname_candidates.as_deref(),
    )?;

    let mut config = role_file_toml;
    let Some(config_table) = config.as_table_mut() else {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!(
                "agent role file at {} must contain a TOML table",
                role_file_label.display()
            ),
        ));
    };
    config_table.remove("name");
    config_table.remove("description");
    config_table.remove("nickname_candidates");

    Ok(ResolvedAgentRoleFile {
        role_name,
        description,
        nickname_candidates,
        config,
    })
}

View on GitHub (pinned to 339751715c)

Solutions

1. Make the agent role file a TOML table (key/value pairs), not a bare value.

When it happens

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