chenhg5/cc-connect · error

create workspace agent for %s: %w

Error message

create workspace agent for %s: %w

What it means

Workspace-agent helper: core.CreateAgent(e.agent.Name(), opts) failed while building the per-workspace agent instance (unknown agent name in the registry or invalid merged opts such as bad run_as settings). The caller falls back to the global agent and only logs this error, so it is usually non-fatal.

Source

Thrown at core/engine.go:3967

	// above, not inherited from the project-level opts that main.go
	// already decorated. See cc-connect#496 and the cc-connect/core/runas.go
	// preamble for why run_as_user has to survive this copy.
	if _, ok := opts["run_as_user"]; !ok {
		if u := e.runAsUser(); u != "" {
			opts["run_as_user"] = u
		}
	}
	if _, ok := opts["run_as_env"]; !ok {
		if ma, ok := e.agent.(interface{ GetRunAsEnv() []string }); ok {
			if env := ma.GetRunAsEnv(); len(env) > 0 {
				opts["run_as_env"] = env
			}
		}
	}

	agent, err := CreateAgent(e.agent.Name(), opts)
	if err != nil {
		return nil, nil, fmt.Errorf("create workspace agent for %s: %w", workspace, err)
	}

	// Wire providers if original agent has them
	if ps, ok := e.agent.(ProviderSwitcher); ok {
		if ps2, ok2 := agent.(ProviderSwitcher); ok2 {
			ps2.SetProviders(ps.ListProviders())
			if active := ps.GetActiveProvider(); active != nil && active.Name != "" {
				ps2.SetActiveProvider(active.Name)
			}
		}
	}

	// Create per-workspace session manager
	h := sha256.Sum256([]byte(workspace))
	sessionFile := filepath.Join(filepath.Dir(e.sessions.StorePath()),
		fmt.Sprintf("%s_ws_%s.json", e.name, hex.EncodeToString(h[:4])))
	sessions := NewSessionManager(sessionFile)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Verify the workspace directory exists and is readable/writable by the process
2. Check the agent factory is registered for e.agent.Name()
3. Inspect the wrapped cause for the concrete constructor failure
4. Validate agent config options (cwd, model, flags) are correct

Example fix

// before
workspace: "/projects/missing-dir"
// after
workspace: "/projects/exists-dir" // ensure path exists before adding workspace

if st, err := os.Stat(workspace); err != nil || !st.IsDir() { return fmt.Errorf("workspace %q unavailable", workspace) }

if _, _, err := engine.CreateWorkspaceAgent(ws); err != nil { log.Fatalf("workspace agent: %v", err) } // inspect wrapped cause with errors.Unwrap

When it happens

Trigger: CreateAgent(e.agent.Name(), opts) fails while creating a workspace-scoped agent — factory lookup fails or constructor validation rejects opts (bad cwd, invalid options).

Common situations: Workspace path does not exist or lacks permissions; agent factory misregistered; invalid agent options derived from config.

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

• session is closed
• job timed out after %v
• resolve relay workspace: %w
• get relay workspace agent: %w
• agent error (no details)

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