mcp_env_vars_missing

mcp_env_vars_missing

Error message

MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings - MCP servers may fail to authenticate.

What it means

While loading MCP server config for Codex, the provider found env var references (e.g. ${GITHUB_TOKEN}) that are not defined in the environment. They are interpolated as empty strings, so the MCP server config is written but servers relying on them for auth may fail at connect time. Surfaced as a providerWarning with code mcp_env_vars_missing.

Source

Thrown at packages/providers/src/codex/provider.ts:943

  ): AsyncGenerator<MessageChunk> {
    const assistantConfig = requestOptions?.assistantConfig ?? {};
    const codexConfig = parseCodexConfig(assistantConfig);
    const providerWarnings: ProviderWarning[] = [];
    let declaredMcpConfigOverrides: CodexConfigOverrides | undefined;

    if (requestOptions?.nodeConfig?.mcp) {
      const mcpPath = requestOptions.nodeConfig.mcp;
      const { servers, serverNames, missingVars } = await loadMcpConfig(
        mcpPath,
        cwd,
        buildMcpEnvSource(requestOptions.env)
      );
      declaredMcpConfigOverrides = buildCodexMcpConfigOverrides(servers);
      getLog().info({ serverNames, mcpPath }, 'codex.mcp_config_loaded');
      if (missingVars.length > 0) {
        const uniqueVars = [...new Set(missingVars)];
        getLog().warn({ missingVars: uniqueVars }, 'codex.mcp_env_vars_missing');
        providerWarnings.push({
          code: 'mcp_env_vars_missing',
          message: `MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings - MCP servers may fail to authenticate.`,
        });
      }
    }

    const suppressWorkflowSkillCatalog = isWorkflowNode(requestOptions);
    const initialConfigOverrides = suppressWorkflowSkillCatalog
      ? withWorkflowSkillCatalogDisabled(declaredMcpConfigOverrides)
      : declaredMcpConfigOverrides;

    for (const warning of providerWarnings) {
      yield { type: 'system', content: `⚠️ ${warning.message}` };
    }

    // 1. Initialize SDK and build thread options
    let codex = await this.createCodexClient(
      codexConfig.codexBinaryPath,

View on GitHub (pinned to 0773b97458)

Solutions

Define the listed env vars in the runtime environment (container env, service unit, or .env the process actually loads)
Check the warn log's missingVars list for exact names and fix typos in the MCP config
Remove or disable the affected MCP servers if their credentials are not needed
Fail fast in deployment by asserting required env vars before starting Archon

Example fix

// before: config references undefined var
{ "command": "npx", "args": ["-y", "mcp-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }
// after: export it in the environment Codex inherits
export GITHUB_TOKEN=ghp_xxx  # or set in container env / .env loaded by the process

Defensive patterns

Strategy: validation

Validate before calling

function findMissingEnvVars(config: string): string[] {
  const refs = [...config.matchAll(/\$\{([A-Z0-9_]+)\}/g)].map((m) => m[1]);
  return [...new Set(refs.filter((name) => !process.env[name]))];
}
// run against the MCP config before starting; must return []

Type guard

function hasEnv(name: string): boolean {
  return typeof process.env[name] === 'string' && process.env[name] !== '';
}

Try / catch

null

Prevention

Keep MCP server credentials in the environment the Archon process actually inherits (container env, service unit, loaded .env)
Check the mcp_env_vars_missing warning's missingVars list at startup and treat it as a deploy blocker
Use one canonical secret store per deployment and reference it consistently in MCP configs
Diff MCP configs between environments after copying them

When it happens

Trigger: provider setup reads MCP server definitions via buildCodexMcpConfigOverrides(servers), collects referenced env vars missing from process.env into missingVars, and pushes the warning when uniqueVars.length > 0.

Common situations: MCP config copied from another machine referencing personal tokens; env vars defined in a shell profile but not in the container/service environment; .env file not loaded; renamed secret in CI.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/fe709d63fdf20c23. Report an issue: GitHub.