chenhg5/cc-connect · error

unknown agent %q, available: %v

Error message

unknown agent %q, available: %v

What it means

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.

Source

Thrown at core/registry.go:59

	return names
}

func ListRegisteredPlatforms() []string {
	names := make([]string, 0, len(platformFactories))
	for k := range platformFactories {
		names = append(names, k)
	}
	return names
}

func CreateAgent(name string, opts map[string]any) (Agent, error) {
	f, ok := agentFactories[name]
	if !ok {
		available := make([]string, 0, len(agentFactories))
		for k := range agentFactories {
			available = append(available, k)
		}
		return nil, fmt.Errorf("unknown agent %q, available: %v", name, available)
	}
	return f(opts)
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Match the name against the 'available: [...]' list in the error and fix config.toml (names are lowercase, case-sensitive)
2. Rebuild including the agent (make build AGENTS=... without excluding it, drop the no_<agent> build tag)
3. After a version upgrade, check config.example.toml / release notes for renamed agents and update the config

Example fix

// before (config.toml)
agent = "claude-code"
// after
agent = "claudecode"

names := core.ListRegisteredAgents()
if !slices.Contains(names, cfgAgentName) {
    return fmt.Errorf("agent %q not registered; available: %v", cfgAgentName, names)
}

a, err := core.CreateAgent(name, opts)
if err != nil {
    if strings.Contains(err.Error(), "unknown agent") {
        return fmt.Errorf("agent %q not compiled in; available: %s", name, strings.Join(core.ListRegisteredAgents(), ", "))
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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').

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• unknown platform %q, available: %v
• resolve home directory: %w
• opencode: %q CLI not found in PATH, install from: https://gi
• acp: agent option "cmd" or "command" is required (path or na
• acp: command %q not found in PATH: %w

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