{"record":{"id":"0c45b489bebc4f1f","repo":"chenhg5/cc-connect","slug":"unknown-agent-q-available-v","errorCode":null,"errorMessage":"unknown agent %q, available: %v","messagePattern":"unknown agent %q, available: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/registry.go","lineNumber":59,"sourceCode":"\treturn names\n}\n\nfunc ListRegisteredPlatforms() []string {\n\tnames := make([]string, 0, len(platformFactories))\n\tfor k := range platformFactories {\n\t\tnames = append(names, k)\n\t}\n\treturn names\n}\n\nfunc CreateAgent(name string, opts map[string]any) (Agent, error) {\n\tf, ok := agentFactories[name]\n\tif !ok {\n\t\tavailable := make([]string, 0, len(agentFactories))\n\t\tfor k := range agentFactories {\n\t\t\tavailable = append(available, k)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"unknown agent %q, available: %v\", name, available)\n\t}\n\treturn f(opts)\n}\n","sourceCodeStart":41,"sourceCodeEnd":63,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/core/registry.go#L41-L63","documentation":"CreateAgent resolves an agent name against factories registered via core.RegisterAgent; an unregistered name returns this error with the list of available agents. It is the agent-side twin of the unknown-platform error.","triggerScenarios":"Config requests an agent name that has no registered factory — typo in config.toml, agent excluded at build time via no_* tags/EXCLUDE, missing plugin_agent_*.go import, or lookup before init() registration; also getOrCreateWorkspaceAgent and NewEnvWithSetup passing dynamic names.","commonSituations":"Renamed agents across versions (config still uses the old name); binary built with AGENTS=claudecode only but config also names codex; case-sensitive mismatch ('ClaudeCode' vs 'claudecode').","solutions":["Match the name against the 'available: [...]' list in the error and fix config.toml (names are lowercase, case-sensitive)","Rebuild including the agent (make build AGENTS=... without excluding it, drop the no_<agent> build tag)","After a version upgrade, check config.example.toml / release notes for renamed agents and update the config"],"exampleFix":"// before (config.toml)\nagent = \"claude-code\"\n// after\nagent = \"claudecode\"","handlingStrategy":"validation","validationCode":"names := core.ListRegisteredAgents()\nif !slices.Contains(names, cfgAgentName) {\n    return fmt.Errorf(\"agent %q not registered; available: %v\", cfgAgentName, names)\n}","typeGuard":null,"tryCatchPattern":"a, err := core.CreateAgent(name, opts)\nif err != nil {\n    if strings.Contains(err.Error(), \"unknown agent\") {\n        return fmt.Errorf(\"agent %q not compiled in; available: %s\", name, strings.Join(core.ListRegisteredAgents(), \", \"))\n    }\n    return err\n}","preventionTips":["Keep config agent names in sync with the AGENTS= make variable used to build the binary","After upgrades, diff config against config.example.toml for renames","Fail fast at startup by listing registered agents and validating config"],"tags":["go","registry","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}