openai/codex · error · PermissionProfileResolutionError

permissions profile `{profile_name}` extends undefined profi

Error message

permissions profile `{profile_name}` extends undefined profile `{parent_profile_name}`

What it means

While following a profile's extends chain, resolve_profile could not find the parent: the name is neither a key in the permissions table nor a built-in from the loader closure, and it does not start with ':' (which would yield UnsupportedBuiltInParent instead). Parents merge before children, so one unresolvable link fails the whole profile.

Source

Thrown at codex-rs/config/src/permissions_toml.rs:125

        }
    }
}

#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PermissionProfileToml {
    pub description: Option<String>,
    pub extends: Option<String>,
    pub workspace_roots: Option<WorkspaceRootsToml>,
    pub filesystem: Option<FilesystemPermissionsToml>,
    pub network: Option<NetworkToml>,
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum PermissionProfileResolutionError {
    #[error("default_permissions refers to undefined profile `{profile_name}`")]
    UndefinedProfile { profile_name: String },
    #[error(
        "permissions profile `{profile_name}` extends undefined profile `{parent_profile_name}`"
    )]
    UndefinedParent {
        profile_name: String,
        parent_profile_name: String,
    },
    #[error(
        "permissions profile `{profile_name}` cannot extend unsupported built-in profile `{parent_profile_name}`"
    )]
    UnsupportedBuiltInParent {
        profile_name: String,
        parent_profile_name: String,
    },
    #[error(
        "permissions profile inheritance cycle detected: {}",
        cycle.join(" -> ")
    )]
    Cycle { cycle: Vec<String> },

View on GitHub (pinned to 339751715c)

Solutions

Define the missing parent `[permissions.<parent>]`
Fix the extends value to the exact name of an existing profile
Drop the extends key if the profile should stand alone

Example fix

# before
[permissions.audited]
extends = "base"

[permissions.baseline]
network = { enabled = false }

# after — match the real parent name
[permissions.audited]
extends = "baseline"

Defensive patterns

Strategy: validation

Validate before calling

use codex_config::PermissionsToml;

// Walk the extends chain before resolve_profile.
fn extends_chain_resolves(
    permissions: &PermissionsToml,
    start: &str,
    is_builtin: impl Fn(&str) -> bool,
) -> Result<(), String> {
    let mut seen = std::collections::HashSet::new();
    let mut name = start.to_string();
    while seen.insert(name.clone()) {
        let Some(profile) = permissions.entries.get(&name) else {
            return Err(format!("profile `{name}` is undefined"));
        };
        match profile.extends.as_deref() {
            Some(parent) => {
                if !parent.starts_with(':')
                    && !permissions.entries.contains_key(parent)
                    && !is_builtin(parent)
                {
                    return Err(format!("`{name}` extends undefined profile `{parent}"));
                }
                name = parent.to_string();
            }
            None => return Ok(()),
        }
    }
    Err("inheritance cycle".to_string())
}

Try / catch

match permissions.resolve_profile(name, builtin_lookup) {
    Err(PermissionProfileResolutionError::UndefinedParent { profile_name, parent_profile_name }) => {
        // Define [permissions.<parent_profile_name>] or fix the extends
        // value in [permissions.<profile_name>].
    }
    Err(e) => return Err(e.into()),
    Ok(profile) => { /* ... */ }
}

Prevention

Rename profiles with grep: update every extends reference in the same commit
Keep base profiles in layers that always load (user/system), never in untrusted project config
Spell parent names exactly — profile keys are case-sensitive

When it happens

Trigger: `[permissions.a] extends = "base"` with no `[permissions.base]` defined and "base" not a built-in — resolving a (or anything extending a) fails.

Common situations: Renaming a base profile without updating children's extends references; the parent living in a config layer that is disabled or not loaded (untrusted project directory); plain typos; sharing a permissions file across projects where only some define the base.

Related errors

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