openai/codex · error · CloudConfigLayerError

failed to parse cloud config fragment {fragment}: {message}

Error message

failed to parse cloud config fragment {fragment}: {message}

What it means

Every enterprise-managed fragment in a cloud config bundle is parsed with toml::from_str inside cloud_config_layers_from_fragments (reached via CloudConfigBundleLayers::from_bundle). When a fragment's contents are not valid TOML, this Parse variant is returned carrying the fragment's name and id plus the underlying toml error, so the offending fragment can be identified precisely.

Source

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

        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
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)
}

View on GitHub (pinned to 339751715c)

Solutions

Copy the fragment's contents out and validate locally - python3 -c 'import tomllib,sys; tomllib.load(open(sys.argv[1],"rb"))' fragment.toml - to see the exact syntax error
Fix the TOML in the admin console or repo that publishes the fragment and let the bundle refresh
Update the Codex client if the backend legitimately emits newer TOML than the installed parser accepts
As a stopgap, remove the offending fragment (matched by the id in the error message) from the bundle so the remaining layers still apply

Example fix

# before: fragment 'policy-main' contents
approval_policy = "never

# after
approval_policy = "never"

Defensive patterns

Strategy: validation

Validate before calling

// Publish-side check: reject fragments that will fail client-side parse
fn fragment_parses(contents: &str) -> bool {
    toml::from_str::<toml::Value>(contents).is_ok()
}

Type guard

pub fn is_cloud_config_parse_error(err: &anyhow::Error) -> bool {
    matches!(
        err.downcast_ref::<CloudConfigLayerError>(),
        Some(CloudConfigLayerError::Parse { .. })
    )
}

Try / catch

match CloudConfigBundleLayers::from_bundle(bundle, &base_dir) {
    Ok(layers) => { /* push layers */ }
    Err(CloudConfigLayerError::Parse { fragment, message }) => {
        // report fragment.name / fragment.id with the TOML error; keep last-good config
    }
    Err(other) => return Err(other.into()),
}

Prevention

Lint every fragment with a TOML parser in the publishing pipeline before it ships
Run strict-config validation on bundle previews
Keep a last-known-good set of layers to fall back to when a refresh fails to parse
Include the fragment id in error dashboards to spot backend regressions quickly

When it happens

Trigger: CloudConfigBundleLayers::from_bundle (or cloud_config_layers_from_fragments) receiving a fragment whose contents have a TOML syntax error: unbalanced brackets or quotes, duplicate keys, invalid escapes, or a construct the parser cannot accept.

Common situations: An admin edits the enterprise fragment in the management console and introduces a typo; a backend template bug emits malformed TOML; version skew where the fragment uses syntax the client's toml parser rejects.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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