openai/codex · error · CloudConfigLayerError

invalid cloud config fragment {fragment}: {message}

Error message

invalid cloud config fragment {fragment}: {message}

What it means

CloudConfigLayerError::Invalid is returned by cloud_config_layers_from_fragments (and its _strict variant) in codex-rs/config/src/cloud_config_layers.rs when an enterprise cloud-delivered config fragment is valid TOML but its contents are rejected downstream: either resolve_relative_paths_in_config_toml fails on a path-typed field, or strict mode finds fields that do not exist on ConfigToml. The {fragment} placeholder renders as 'name (id)', identifying exactly which bundle entry is bad.

Source

Thrown at codex-rs/config/src/cloud_config_layers.rs:61

pub struct CloudConfigFragmentSource {
    pub id: String,
    pub name: String,
}

impl fmt::Display for CloudConfigFragmentSource {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} ({})", self.name, self.id)
    }
}

#[derive(Debug, Error, PartialEq, Eq)]
pub enum CloudConfigLayerError {
    #[error("failed to parse cloud config fragment {fragment}: {message}")]
    Parse {
        fragment: CloudConfigFragmentSource,
        message: String,
    },
    #[error("invalid cloud config fragment {fragment}: {message}")]
    Invalid {
        fragment: CloudConfigFragmentSource,
        message: String,
    },
}

pub fn cloud_config_layers_from_fragments(
    fragments: impl IntoIterator<Item = CloudConfigFragment>,
    base_dir: &AbsolutePathBuf,
) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError> {
    cloud_config_layers_from_fragments_impl(fragments, base_dir, /*strict_config*/ false)
}

pub(crate) fn cloud_config_layers_from_fragments_strict(
    fragments: impl IntoIterator<Item = CloudConfigFragment>,
    base_dir: &AbsolutePathBuf,
) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError> {
    cloud_config_layers_from_fragments_impl(fragments, base_dir, /*strict_config*/ true)

View on GitHub (pinned to 339751715c)

Solutions

  1. Read the fragment name and id in the message, fix the reported field in that managed fragment in the admin console, and republish
  2. If the message concerns a path, make the path field valid and resolvable against the cloud config base directory (or absolute)
  3. If strict mode reports an unknown field, remove the typo'd or unsupported key from the fragment
  4. Update codex to a version whose ConfigToml schema includes the fragment field if the field is legitimately new

Example fix

# fragment contents (before)
model = "gpt-5.1-codex"
approvals = "never"        # unknown key -> Invalid in strict mode

# fragment contents (after)
model = "gpt-5.1-codex"
approval_policy = "never"
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight a fragment before handing it to the layer builder
let value: toml::Value = toml::from_str(&fragment.contents)
    .map_err(|e| format!("fragment {} is not valid TOML: {e}", fragment.name))?;
// strict mode: also reject keys ConfigToml does not know before submitting

Try / catch

match cloud_config_layers_from_fragments(fragments, &base_dir) {
    Ok(layers) => { /* push onto stack */ }
    Err(CloudConfigLayerError::Invalid { fragment, message }) => {
        tracing::error!("managed fragment {} ({}) rejected: {message}", fragment.name, fragment.id);
        // surface to the IT admin; do not silently drop the managed layer
    }
    Err(CloudConfigLayerError::Parse { .. }) => { /* handle syntax error */ }
}

Prevention

When it happens

Trigger: Calling cloud_config_layers_from_fragments / cloud_config_layers_from_fragments_strict with a CloudConfigFragment whose contents contains a path field that cannot be resolved against base_dir, or (strict mode) an unknown or mistyped key such as 'approvals' that ConfigToml does not recognize; the fragment set comes from a cloud/enterprise config bundle in backend priority order.

Common situations: An org admin publishes a managed fragment with a typo'd key or an invalid relative path; version skew where the local codex build's ConfigToml schema predates a new fragment key; base_dir changing after CODEX_HOME moves.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

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