gemini: %q CLI not found in PATH, install with: npm i -g @go

Error message

gemini: %q CLI not found in PATH, install with: npm i -g @google/gemini-cli

What it means

New() verifies the gemini CLI binary exists in PATH via exec.LookPath before constructing the Agent. If it is missing, construction fails immediately with an actionable install hint rather than failing later at session start. This is an early environment validation error.

Source

Thrown at agent/gemini/gemini.go:75

	switch v := opts["timeout_mins"].(type) {
	case int64:
		timeoutMins = v
	case int:
		timeoutMins = int64(v)
	case float64:
		timeoutMins = int64(v)
	default:
		if v != nil {
			slog.Debug("gemini: timeout_mins has unexpected type", "type", fmt.Sprintf("%T", v))
		}
	}
	var timeout time.Duration
	if timeoutMins > 0 {
		timeout = time.Duration(timeoutMins) * time.Minute
	}

	if _, err := exec.LookPath(cmd); err != nil {
		return nil, fmt.Errorf("gemini: %q CLI not found in PATH, install with: npm i -g @google/gemini-cli", cmd)
	}

	return &Agent{
		workDir:      workDir,
		model:        model,
		mode:         mode,
		cmd:          cmd,
		cliExtraArgs: extraArgs,
		configEnv:    core.ParseConfigEnv(opts),
		timeout:      timeout,
		activeIdx:    -1,
	}, nil
}

func normalizeMode(raw string) string {
	switch strings.ToLower(strings.TrimSpace(raw)) {
	case "yolo", "auto", "force", "bypasspermissions":
		return "yolo"

View on GitHub (pinned to 4000b2338a)

Solutions

Install the CLI: `npm i -g @google/gemini-cli`
Verify with `which gemini` in the same environment cc-connect runs in
For daemons, set the full PATH (e.g. /usr/local/bin or npm global bin) in the systemd unit or config env
If the binary exists under a different name/path, symlink it into PATH

Example fix

// before: agent fails at startup with cryptic PATH issues in daemon
exec.Command("gemini", "--version")
// after: pin absolute path / ensure PATH in service
// /etc/systemd/system/cc-connect.service
// Environment=PATH=/usr/local/bin:/home/user/.npm-global/bin

Defensive patterns

Strategy: validation

Validate before calling

if _, err := exec.LookPath("gemini"); err != nil {
  return fmt.Errorf("gemini CLI not installed or not in PATH; run: npm i -g @google/gemini-cli")
}

Try / catch

agent, err := gemini.New(...)
if err != nil && strings.Contains(err.Error(), "CLI not found in PATH") {
  log.Fatal("install gemini CLI and ensure it is on the daemon's PATH")
}

Prevention

Install the CLI globally and verify with `which gemini` as the same user the daemon runs as
Set an explicit PATH in systemd/Docker environments
Add a startup doctor check (cc-connect doctor) that validates agent binaries

When it happens

Trigger: Calling New() (via CreateAgent from config) when the `gemini` binary is not installed or not on the PATH of the cc-connect process.

Common situations: Gemini CLI never installed; installed locally via npm without -g so it's not in PATH; cc-connect runs as a systemd service whose PATH lacks the user's npm global bin directory; PATH differs between shell and daemon.

Related errors

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/70a671d1978e0ebd. Report an issue: GitHub.