chenhg5/cc-connect · error

config: %s.agent.type is required

Error message

config: %s.agent.type is required

What it means

Every project must declare which coding agent it uses via the agent.type field (e.g. "claudecode", "codex", "gemini"). The validator rejects a project whose Agent.Type is empty because the engine cannot construct an agent instance from an unknown/blank type name.

Source

Thrown at config/config.go:1032

	}
	if c.Relay.TimeoutSecs != nil && *c.Relay.TimeoutSecs < 0 {
		return fmt.Errorf("config: relay.timeout_secs must be >= 0")
	}
	switch strings.ToLower(strings.TrimSpace(c.Relay.Visibility)) {
	case "", "full", "summary", "none":
	default:
		return fmt.Errorf("config: relay.visibility must be \"full\", \"summary\", or \"none\"")
	}
	if len(c.Projects) == 0 {
		return fmt.Errorf("config: at least one [[projects]] entry is required")
	}
	for i, proj := range c.Projects {
		prefix := fmt.Sprintf("projects[%d]", i)
		if proj.Name == "" {
			return fmt.Errorf("config: %s.name is required", prefix)
		}
		if proj.Agent.Type == "" {
			return fmt.Errorf("config: %s.agent.type is required", prefix)
		}
		if len(proj.Platforms) == 0 && !permissive {
			return fmt.Errorf("config: %s needs at least one [[projects.platforms]]", prefix)
		}
		for j, p := range proj.Platforms {
			if p.Type == "" {
				return fmt.Errorf("config: %s.platforms[%d].type is required", prefix, j)
			}
		}
		if proj.Mode == "multi-workspace" {
			if proj.BaseDir == "" {
				return fmt.Errorf("project %q: multi-workspace mode requires base_dir", proj.Name)
			}
			if _, ok := proj.Agent.Options["work_dir"]; ok {
				return fmt.Errorf("project %q: multi-workspace mode conflicts with agent work_dir (use base_dir instead)", proj.Name)
			}
		}
		if proj.ResetOnIdleMins != nil && *proj.ResetOnIdleMins < 0 {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add agent.type = "<agent>" to the failing [[projects]] block (index in the message)
2. Use an agent name that is registered/compiled in (e.g. "claudecode", "codex", "opencode") — see config.example.toml
3. Ensure the table header is exactly [projects.agent], singular

Example fix

// before
[[projects]]
name = "my-app"
[[projects.platforms]]
type = "telegram"
// after
[[projects]]
name = "my-app"
agent.type = "claudecode"
[[projects.platforms]]
type = "telegram"

for i, p := range cfg.Projects {
    if p.Agent.Type == "" {
        return fmt.Errorf("projects[%d].agent.type is required", i)
    }
}

When it happens

Trigger: A [[projects]] block with no [projects.agent] table, or with [projects.agent] present but type missing/empty, so proj.Agent.Type == "" during validation.

Common situations: Adding a new project and copying only the platforms section; mistyping the table header (e.g. [projects.agents] plural) so type lands nowhere; deleting the agent table while troubleshooting.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• tmux: 'session' option is required (name of the tmux session
• config: relay.visibility must be "full", "summary", or "none
• config: at least one [[projects]] entry is required
• config: %s.name is required
• config: %s needs at least one [[projects.platforms]]

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