{"record":{"id":"65b2a80770eb8b62","repo":"chenhg5/cc-connect","slug":"acp-agent-option-cmd-or-command-is-required","errorCode":null,"errorMessage":"acp: agent option \"cmd\" or \"command\" is required (path or name of the ACP agent binary)","messagePattern":"acp: agent option \"cmd\" or \"command\" is required \\(path or name of the ACP agent binary\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/acp/agent.go","lineNumber":78,"sourceCode":"\treportModes(block acpModesBlock)\n\treportListSupported(supported bool)\n}\n\n// Ensure *Agent satisfies sessionCallbacks at compile time.\nvar _ sessionCallbacks = (*Agent)(nil)\n\n// New builds an acp agent from project options.\n// Required: options[\"command\"] — executable name or path for the ACP agent.\n// Optional: options[\"args\"], options[\"env\"], options[\"auth_method\"],\n// options[\"display_name\"], options[\"mode\"].\nfunc New(opts map[string]any) (core.Agent, error) {\n\tworkDir, _ := opts[\"work_dir\"].(string)\n\tif workDir == \"\" {\n\t\tworkDir = \".\"\n\t}\n\tcmdStr, cliExtraArgs := core.ParseCmdOpts(opts, \"\")\n\tif cmdStr == \"\" {\n\t\treturn nil, fmt.Errorf(\"acp: agent option \\\"cmd\\\" or \\\"command\\\" is required (path or name of the ACP agent binary)\")\n\t}\n\tif _, err := exec.LookPath(cmdStr); err != nil {\n\t\treturn nil, fmt.Errorf(\"acp: command %q not found in PATH: %w\", cmdStr, err)\n\t}\n\n\targs := parseStringSlice(opts[\"args\"])\n\tstaticEnv := envMapFromOpts(opts)\n\textra := envPairsFromOpts(opts)\n\tauthMethod, _ := opts[\"auth_method\"].(string)\n\tauthMethod = strings.TrimSpace(authMethod)\n\tdisplayName, _ := opts[\"display_name\"].(string)\n\tdisplayName = strings.TrimSpace(displayName)\n\tif displayName == \"\" {\n\t\tdisplayName = \"ACP\"\n\t}\n\tmode, _ := opts[\"mode\"].(string)\n\tmode = strings.TrimSpace(mode)\n","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/agent/acp/agent.go#L60-L96","documentation":"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.","triggerScenarios":"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).","commonSituations":"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'.","solutions":["Add the cmd option to the acp agent config: cmd = \"/path/to/agent-binary\" or cmd = \"agent-name\" (resolved via PATH).","Alternatively use the key name \"command\" if your config style prefers it — both are accepted.","Check that your config templating actually fills the cmd value (print resolved config / avoid empty interpolations).","Confirm the option lives under the correct agent section ([agents.acp]) and isn't shadowed by a typo'd table name."],"exampleFix":"// before (config.toml)\n[agents.acp]\nargs = [\"--stdio\"]\n// after\n[agents.acp]\ncmd = \"my-acp-agent\"\nargs = [\"--stdio\"]","handlingStrategy":"validation","validationCode":"func validateACPOpts(opts map[string]any) error {\n    cmd, _ := core.ParseCmdOpts(opts, \"\")\n    if cmd == \"\" {\n        return errors.New(\"acp agent config must set cmd or command\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"agent, err := core.CreateAgent(\"acp\", opts)\nif err != nil && strings.Contains(err.Error(), \"cmd\\\" or \\\"command\\\" is required\") {\n    return fmt.Errorf(\"config error: add 'cmd = ...' to [agents.acp] in config.toml: %w\", err)\n}","preventionTips":["Always set cmd in the [agents.acp] config section","Use 'cmd' or 'command' exactly — not binary/executable/path","Render and inspect templated configs to catch empty interpolations","Run `cc-connect` config validation/doctor before going live"],"tags":["acp","configuration","missing-option","agent"],"backgroundTag":"missing-required-option","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"}