openai/codex · error · ExecutorPluginMcpProviderError

failed to resolve MCP config path `{relative_path}` below se

Error message

failed to resolve MCP config path `{relative_path}` below selected plugin `{plugin_id}` at `{root}`: {source}

What it means

load_from_file_system joins DEFAULT_MCP_CONFIG_FILE ('.mcp.json') onto the plugin root PathUri; a PathUriParseError from that join surfaces as InvalidConfigPath with the root and relative segment. The plugin root itself does not compose with the relative path — a malformed or exotic root locator rather than a user file problem.

Source

Thrown at codex-rs/ext/mcp/src/executor_plugin/provider.rs:31

use thiserror::Error;

const DEFAULT_MCP_CONFIG_FILE: &str = ".mcp.json";

/// Loads MCP declarations from resolved plugins through their owning executor.
#[derive(Clone, Copy, Debug, Default)]
pub(super) struct ExecutorPluginMcpProvider;

/// Failure to load an executor plugin's MCP declarations.
#[derive(Debug, Error)]
pub(super) enum ExecutorPluginMcpProviderError {
    #[error("failed to read MCP config for selected plugin `{plugin_id}` at `{path}`: {source}")]
    ReadConfig {
        plugin_id: String,
        path: PathUri,
        #[source]
        source: io::Error,
    },
    #[error(
        "failed to resolve MCP config path `{relative_path}` below selected plugin `{plugin_id}` at `{root}`: {source}"
    )]
    InvalidConfigPath {
        plugin_id: String,
        root: PathUri,
        relative_path: &'static str,
        #[source]
        source: PathUriParseError,
    },
    #[error("failed to parse MCP config for selected plugin `{plugin_id}` at `{path}`: {source}")]
    ParseConfig {
        plugin_id: String,
        path: PathUri,
        #[source]
        source: serde_json::Error,
    },
}

View on GitHub (pinned to 339751715c)

Solutions

1. Inspect the plugin root URI printed as {root} for an invalid scheme or malformed segments.
2. Re-register or reinstall the plugin environment so the root resolves cleanly.
3. Report upstream if a valid-looking root reproducibly fails to join.

match mcp_provider.load(&plugin).await {
    Err(ExecutorPluginMcpProviderError::InvalidConfigPath { plugin_id, root, source }) => {
        tracing::error!(%plugin_id, %root, %source, "plugin root cannot host .mcp.json; reinstall plugin");
        Vec::new()
    }
    r => r?,
}

When it happens

Trigger: A resolved environment plugin whose root PathUri has a scheme or shape that cannot take '.mcp.json' as a child (corrupt registration, unusual remote URI).

Common situations: Broken plugin environment registration; hand-edited plugin root locators; version skew between codex-plugin resolution and the path-URI utilities.

Related errors

• failed to read MCP config for selected plugin `{plugin_id}`
• failed to parse MCP config for selected plugin `{plugin_id}`
• failed to read app config for selected plugin `{plugin_id}`
• failed to parse app config for selected plugin `{plugin_id}`
• path '{path}' {reason}

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