{"record":{"id":"20543b2222a3f9de","repo":"chenhg5/cc-connect","slug":"codex-q-cli-not-found-in-path-install-with-npm","errorCode":null,"errorMessage":"codex: %q CLI not found in PATH, install with: npm install -g @openai/codex","messagePattern":"codex: %q CLI not found in PATH, install with: npm install -g @openai/codex","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/codex/codex.go","lineNumber":75,"sourceCode":"\tif workDir == \"\" {\n\t\tworkDir = \".\"\n\t}\n\tmodel, _ := opts[\"model\"].(string)\n\treasoningEffort, _ := opts[\"reasoning_effort\"].(string)\n\tmode, _ := opts[\"mode\"].(string)\n\tbackend, _ := opts[\"backend\"].(string)\n\tappServerURL, _ := opts[\"app_server_url\"].(string)\n\tcodexHome, _ := opts[\"codex_home\"].(string)\n\tsystemPrompt, _ := opts[\"system_prompt\"].(string)\n\tappendPrompt, _ := opts[\"append_system_prompt\"].(string)\n\tmode = normalizeMode(mode)\n\tbackend = normalizeBackend(backend)\n\tappServerURL = normalizeAppServerURL(appServerURL)\n\n\tcmd, cliExtraArgs := core.ParseCmdOpts(opts, \"codex\")\n\n\tif _, err := exec.LookPath(cmd); err != nil {\n\t\treturn nil, fmt.Errorf(\"codex: %q CLI not found in PATH, install with: npm install -g @openai/codex\", cmd)\n\t}\n\n\t// Parse project-level env from opts[\"env\"] (set via [projects.agent.options.env] in config.toml).\n\t// Stored separately from runtime sessionEnv so SetSessionEnv calls cannot overwrite it.\n\t// MergeEnv semantics ensure these override any same-named keys inherited from os.Environ()\n\t// when the codex subprocess is spawned (e.g. user-scoped HTTPS_PROXY leaking into the agent).\n\tvar configEnv []string\n\tif envMap, ok := opts[\"env\"].(map[string]string); ok {\n\t\tfor k, v := range envMap {\n\t\t\tconfigEnv = append(configEnv, k+\"=\"+v)\n\t\t}\n\t} else if envMap, ok := opts[\"env\"].(map[string]any); ok {\n\t\tfor k, v := range envMap {\n\t\t\tif s, ok := v.(string); ok {\n\t\t\t\tconfigEnv = append(configEnv, k+\"=\"+s)\n\t\t\t}\n\t\t}\n\t}","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/agent/codex/codex.go#L57-L93","documentation":"The codex agent constructor validates at creation time that the `codex` CLI binary exists on PATH via exec.LookPath. If the binary cannot be found (or the configured command name resolves to nothing), New() refuses to build the agent and returns this error instead of failing later at session start. It exists so misconfiguration surfaces immediately with an actionable install hint.","triggerScenarios":"Calling core.CreateAgent(\"codex\", opts) / New() when opts[\"cmd\"] names an executable absent from PATH, or when the default \"codex\" command is not installed. Also triggered in tests that construct the agent without a stub binary on PATH.","commonSituations":"Fresh machines or CI containers where npm global bin is not on PATH; user installed codex under a different name or via a version manager not sourced in the service environment; config sets cmd to a custom wrapper that does not exist; systemd/daemon environments with a restricted PATH missing ~/.npm-global/bin.","solutions":["Install the CLI: npm install -g @openai/codex, then verify with `which codex`.","If codex is installed but not found, add its directory (e.g. $(npm config get prefix)/bin) to PATH for the process running cc-connect.","If you use a custom binary name/path, set opts[\"cmd\"] in [projects.agent.options] to an executable that exists and is executable.","For daemons, ensure the systemd/launchd unit environment includes the PATH entry containing codex."],"exampleFix":"// before\nagent, err := codex.New(core.AgentOptions{}) // fails: CLI not found\n// after\n// config.toml\n[projects.agent.options]\ncmd = \"/usr/local/bin/codex\"  # or install: npm install -g @openai/codex","handlingStrategy":"validation","validationCode":"cmd := \"codex\" // or opts[\"cmd\"]\nif _, err := exec.LookPath(cmd); err != nil {\n    return fmt.Errorf(\"codex CLI %q not installed; run: npm install -g @openai/codex\", cmd)\n}\nagent, err := codex.New(opts)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add a startup doctor check (cc-connect doctor) that verifies each agent CLI is on PATH.","Install global npm CLIs into a fixed prefix and add it to PATH in service unit files.","Pin the codex binary path via opts[\"cmd\"] in config.toml instead of relying on PATH.","Smoke-test agent construction in CI containers before deploy."],"tags":["cli","path","dependency-missing","initialization"],"backgroundTag":"command-not-found","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}