{"record":{"id":"fe709d63fdf20c23","repo":"coleam00/Archon","slug":"mcp-env-vars-missing-fe709d","errorCode":"mcp_env_vars_missing","errorMessage":"MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings - MCP servers may fail to authenticate.","messagePattern":"MCP config references undefined env vars: (.+?)\\. These will be empty strings - MCP servers may fail to authenticate\\.","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/providers/src/codex/provider.ts","lineNumber":943,"sourceCode":"  ): AsyncGenerator<MessageChunk> {\n    const assistantConfig = requestOptions?.assistantConfig ?? {};\n    const codexConfig = parseCodexConfig(assistantConfig);\n    const providerWarnings: ProviderWarning[] = [];\n    let declaredMcpConfigOverrides: CodexConfigOverrides | undefined;\n\n    if (requestOptions?.nodeConfig?.mcp) {\n      const mcpPath = requestOptions.nodeConfig.mcp;\n      const { servers, serverNames, missingVars } = await loadMcpConfig(\n        mcpPath,\n        cwd,\n        buildMcpEnvSource(requestOptions.env)\n      );\n      declaredMcpConfigOverrides = buildCodexMcpConfigOverrides(servers);\n      getLog().info({ serverNames, mcpPath }, 'codex.mcp_config_loaded');\n      if (missingVars.length > 0) {\n        const uniqueVars = [...new Set(missingVars)];\n        getLog().warn({ missingVars: uniqueVars }, 'codex.mcp_env_vars_missing');\n        providerWarnings.push({\n          code: 'mcp_env_vars_missing',\n          message: `MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings - MCP servers may fail to authenticate.`,\n        });\n      }\n    }\n\n    const suppressWorkflowSkillCatalog = isWorkflowNode(requestOptions);\n    const initialConfigOverrides = suppressWorkflowSkillCatalog\n      ? withWorkflowSkillCatalogDisabled(declaredMcpConfigOverrides)\n      : declaredMcpConfigOverrides;\n\n    for (const warning of providerWarnings) {\n      yield { type: 'system', content: `⚠️ ${warning.message}` };\n    }\n\n    // 1. Initialize SDK and build thread options\n    let codex = await this.createCodexClient(\n      codexConfig.codexBinaryPath,","sourceCodeStart":925,"sourceCodeEnd":961,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/providers/src/codex/provider.ts#L925-L961","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: config references undefined var\n{ \"command\": \"npx\", \"args\": [\"-y\", \"mcp-github\"], \"env\": { \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\" } }\n// after: export it in the environment Codex inherits\nexport GITHUB_TOKEN=ghp_xxx  # or set in container env / .env loaded by the process","handlingStrategy":"validation","validationCode":"function findMissingEnvVars(config: string): string[] {\n  const refs = [...config.matchAll(/\\$\\{([A-Z0-9_]+)\\}/g)].map((m) => m[1]);\n  return [...new Set(refs.filter((name) => !process.env[name]))];\n}\n// run against the MCP config before starting; must return []","typeGuard":"function hasEnv(name: string): boolean {\n  return typeof process.env[name] === 'string' && process.env[name] !== '';\n}","tryCatchPattern":"null","preventionTips":["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"],"tags":["mcp","env-vars","configuration","codex"],"backgroundTag":"missing-env-var","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}