chenhg5/cc-connect · error

acp: command %q not found in PATH: %w

Error message

acp: command %q not found in PATH: %w

What it means

After reading the 'cmd'/'command' option, the ACP agent constructor runs exec.LookPath on it. If the binary cannot be found in PATH (or the given path doesn't exist / isn't executable), New returns this wrapped error including the LookPath detail. The agent process was never started; this is a pre-flight check.

Source

Thrown at agent/acp/agent.go:81

// Ensure *Agent satisfies sessionCallbacks at compile time.
var _ sessionCallbacks = (*Agent)(nil)

// New builds an acp agent from project options.
// Required: options["command"] — executable name or path for the ACP agent.
// Optional: options["args"], options["env"], options["auth_method"],
// options["display_name"], options["mode"].
func New(opts map[string]any) (core.Agent, error) {
	workDir, _ := opts["work_dir"].(string)
	if workDir == "" {
		workDir = "."
	}
	cmdStr, cliExtraArgs := core.ParseCmdOpts(opts, "")
	if cmdStr == "" {
		return nil, fmt.Errorf("acp: agent option \"cmd\" or \"command\" is required (path or name of the ACP agent binary)")
	}
	if _, err := exec.LookPath(cmdStr); err != nil {
		return nil, fmt.Errorf("acp: command %q not found in PATH: %w", cmdStr, err)
	}

	args := parseStringSlice(opts["args"])
	staticEnv := envMapFromOpts(opts)
	extra := envPairsFromOpts(opts)
	authMethod, _ := opts["auth_method"].(string)
	authMethod = strings.TrimSpace(authMethod)
	displayName, _ := opts["display_name"].(string)
	displayName = strings.TrimSpace(displayName)
	if displayName == "" {
		displayName = "ACP"
	}
	mode, _ := opts["mode"].(string)
	mode = strings.TrimSpace(mode)

	return &Agent{
		workDir:     workDir,
		cmd:          cmdStr,

View on GitHub (pinned to 4000b2338a)

Solutions

1. Use an absolute path to the binary in cmd, e.g. cmd = "/home/user/.local/bin/my-acp-agent".
2. Install the binary or `go install`/`npm i -g` it, and verify with `which <name>`.
3. Extend the service's PATH (systemd: Environment=PATH=...) or set the env option so LookPath succeeds.
4. Check the executable bit (`chmod +x`) if the file exists at the given path.

Example fix

// before (config.toml)
[agents.acp]
cmd = "gemini-acp"  # not on systemd's PATH
// after
[agents.acp]
cmd = "/home/dev/.npm-global/bin/gemini-acp"

func checkACPCmd(cmd string) error {
    p, err := exec.LookPath(cmd)
    if err != nil {
        return fmt.Errorf("acp binary %q not found in PATH (set an absolute path for daemons): %w", cmd, err)
    }
    fmt.Println("acp binary resolved to", p)
    return nil
}

agent, err := core.CreateAgent("acp", opts)
var le *exec.Error
if errors.As(err, &le) || strings.Contains(err.Error(), "not found in PATH") {
    return fmt.Errorf("fix [agents.acp].cmd: use an absolute path usable by the service user: %w", err)
}

When it happens

Trigger: core.CreateAgent("acp", opts) where opts["cmd"] names a binary not present in any PATH directory, references an absolute path that doesn't exist or lacks the executable bit, or relies on an interpreter/alias that isn't on the daemon's PATH.

Common situations: Running cc-connect as a systemd service whose PATH is minimal and lacks nvm/homebrew locations (~/.local/bin, /usr/local/bin); typos in the binary name; installed the agent under a user account but the daemon runs as another user; binary not yet built.

Related errors

• acp: agent option "cmd" or "command" is required (path or na
• opencode: %q CLI not found in PATH, install from: https://gi
• acp: probe stdin pipe: %w
• acp: probe stdout pipe: %w
• acp: probe start %s: %w

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