openai/codex · error · ConstraintError

invalid requirement for MCP server `{server_name}` (set by {

Error message

invalid requirement for MCP server `{server_name}` (set by {requirement_source}): {reason}

What it means

ConstraintError::McpServerRequirementParse (codex-rs/config/src/constraint.rs:31) is returned when a per-server MCP requirement inside a requirements layer fails to parse. The error names the offending MCP server and the RequirementSource whose file carries it, plus the underlying reason, so the bad stanza can be located directly.

Source

Thrown at codex-rs/config/src/constraint.rs:31

        field_name: &'static str,
        candidate: String,
        allowed: String,
        requirement_source: RequirementSource,
    },

    #[error("To use model `{model}`, you need to use auto review.")]
    AutoReviewRequired { model: String },

    #[error("field `{field_name}` cannot be empty")]
    EmptyField { field_name: String },

    #[error("invalid rules in requirements (set by {requirement_source}): {reason}")]
    ExecPolicyParse {
        requirement_source: RequirementSource,
        reason: String,
    },

    #[error(
        "invalid requirement for MCP server `{server_name}` (set by {requirement_source}): {reason}"
    )]
    McpServerRequirementParse {
        server_name: String,
        requirement_source: RequirementSource,
        reason: String,
    },
}

impl ConstraintError {
    pub fn empty_field(field_name: impl Into<String>) -> Self {
        Self::EmptyField {
            field_name: field_name.into(),
        }
    }
}

pub type ConstraintResult<T> = Result<T, ConstraintError>;

View on GitHub (pinned to 339751715c)

Solutions

1. Fix the stanza for the server named in server_name in the requirements file named by requirement_source
2. Use the reason text to identify the exact key or type at fault and align it with the current MCP requirement schema
3. Reload or redeploy the requirements after the fix

// Dry-parse the requirements file, including MCP server stanzas, before deploying
let _: RequirementsToml = toml::from_str(&requirements_str)
    .map_err(|e| format!("requirements would fail to load: {e}"))?;

match build_constraints(...) {
    Err(ConstraintError::McpServerRequirementParse { server_name, requirement_source, reason }) => {
        eprintln!("bad requirement for MCP server {server_name} in {requirement_source}: {reason}");
    }
    r => r?,
}

When it happens

Trigger: A requirements TOML entry constraining an MCP server (under its mcp server requirements table) has an unknown key, wrong type, or malformed structure; parsing happens while the constraint system builds the constrained MCP server config.

Common situations: Typing an unrecognized key under an MCP server requirement; schema drift after upgrading codex; requirements synced between environments running different codex versions.

Related errors

• invalid rules in requirements (set by {requirement_source}):
• InvalidData
• Invalid MCP server name '{server_name}': must match pattern
• invalid cloud config fragment {fragment}: {message}
• invalid value for `{field_name}`: `{candidate}` is not in th

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