chenhg5/cc-connect · error

acp: agent option "cmd" or "command" is required (path or na

Error message

acp: agent option "cmd" or "command" is required (path or name of the ACP agent binary)

What it means

The ACP agent constructor (agent/acp/agent.go New) requires an 'cmd' or 'command' option specifying the executable of the ACP agent binary. core.ParseCmdOpts extracts it from the options map; if it comes back empty, New refuses to build the agent because it would have no process to launch. This is a configuration-time validation error, not a runtime one.

Source

Thrown at agent/acp/agent.go:78

	reportModes(block acpModesBlock)
	reportListSupported(supported bool)
}

// 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)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add the cmd option to the acp agent config: cmd = "/path/to/agent-binary" or cmd = "agent-name" (resolved via PATH).
2. Alternatively use the key name "command" if your config style prefers it — both are accepted.
3. Check that your config templating actually fills the cmd value (print resolved config / avoid empty interpolations).
4. Confirm the option lives under the correct agent section ([agents.acp]) and isn't shadowed by a typo'd table name.

Example fix

// before (config.toml)
[agents.acp]
args = ["--stdio"]
// after
[agents.acp]
cmd = "my-acp-agent"
args = ["--stdio"]

func validateACPOpts(opts map[string]any) error {
    cmd, _ := core.ParseCmdOpts(opts, "")
    if cmd == "" {
        return errors.New("acp agent config must set cmd or command")
    }
    return nil
}

agent, err := core.CreateAgent("acp", opts)
if err != nil && strings.Contains(err.Error(), "cmd\" or \"command\" is required") {
    return fmt.Errorf("config error: add 'cmd = ...' to [agents.acp] in config.toml: %w", err)
}

When it happens

Trigger: Creating the acp agent via core.CreateAgent("acp", opts) where opts lacks both "cmd" and "command" keys, or where they are present but resolve to an empty string (e.g. opts["cmd"] = "" or an empty list after parsing).

Common situations: config.toml [agents.acp] section missing the cmd field; defining only args/env without cmd; a templated config where cmd expansion produced an empty string; renaming the option to something unrecognized like 'binary' or 'executable'.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• acp: command %q not found in PATH: %w
• acp: probe stdin pipe: %w
• acp: probe stdout pipe: %w
• acp: probe start %s: %w
• acp: initialize: %w

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