chenhg5/cc-connect · error

project %q: multi-workspace mode requires base_dir

Error message

project %q: multi-workspace mode requires base_dir

What it means

When a project's mode is "multi-workspace", it must define base_dir — the root directory under which per-workspace directories are created. Because multi-workspace mode derives working directories dynamically, a missing base_dir leaves the engine with no location to operate in, so validation fails.

Source

Thrown at config/config.go:1044

	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 {
			return fmt.Errorf("config: %s.reset_on_idle_mins must be >= 0", prefix)
		}
		if proj.AgentSessionIdleTimeoutMins != nil && *proj.AgentSessionIdleTimeoutMins < 0 {
			return fmt.Errorf("config: %s.agent_session_idle_timeout_mins must be >= 0", prefix)
		}
		if err := validateRunAsUser(prefix, proj.RunAsUser); err != nil {
			return err
		}
		if err := validateRunAsEnv(prefix, proj.RunAsEnv); err != nil {
			return err
		}
		if err := validateReferenceConfig(prefix, proj.References); err != nil {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add base_dir = "/absolute/path/to/workspaces" to the multi-workspace project
2. Remove mode = "multi-workspace" if you intended a single fixed working directory (use agent work_dir instead)
3. Ensure base_dir points to an existing or creatable directory

Example fix

// before
[[projects]]
name = "my-app"
mode = "multi-workspace"
// after
[[projects]]
name = "my-app"
mode = "multi-workspace"
base_dir = "/home/me/workspaces"

if proj.Mode == "multi-workspace" && strings.TrimSpace(proj.BaseDir) == "" {
    return fmt.Errorf("multi-workspace project %q needs base_dir", proj.Name)
}

When it happens

Trigger: Setting mode = "multi-workspace" on a [[projects]] entry while leaving base_dir unset or empty, then loading the config.

Common situations: Switching a project from single-workspace to multi-workspace mode without adding the required base_dir; copying a multi-workspace example but omitting the path; environments where the base_dir line was environment-specific and removed.

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.agent.type is required

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