chenhg5/cc-connect · error

get relay workspace agent: %w

Error message

get relay workspace agent: %w

What it means

After the relay target workspace was resolved, getOrCreateWorkspaceAgent(workspace) failed to create or fetch the agent instance bound to that workspace; the cause is wrapped as 'get relay workspace agent: %w'. This means routing succeeded but the per-workspace agent could not be instantiated (e.g. agent type unknown, initialization error, resource limits).

Source

Thrown at core/engine.go:15951

	if !e.multiWorkspace || e.workspaceBindings == nil {
		return e.agent, e.sessions, relaySessionKey, nil
	}

	channelKey := workspaceChannelKey(platformName, chatID)
	workspace, _, err := e.resolveWorkspace(e.platformForName(platformName), chatID)
	if err != nil {
		return nil, nil, "", fmt.Errorf("resolve relay workspace: %w", err)
	}
	if workspace == "" {
		if b, _, usable := e.lookupEffectiveWorkspaceBinding(channelKey); b != nil && !usable {
			return nil, nil, "", fmt.Errorf("workspace binding unavailable for source channel %q", channelKey)
		}
		return nil, nil, "", fmt.Errorf("no workspace binding for source channel %q", channelKey)
	}

	agent, sessions, err := e.getOrCreateWorkspaceAgent(workspace)
	if err != nil {
		return nil, nil, "", fmt.Errorf("get relay workspace agent: %w", err)
	}
	if ws := e.workspacePool.Get(workspace); ws != nil {
		ws.Touch()
	}
	return agent, sessions, relaySessionKey, nil
}

// HandleRelay processes a relay message synchronously: starts or resumes a
// dedicated relay session, sends the message to the agent, and blocks until
// the complete response is collected (or the relay context times out).
func (e *Engine) HandleRelay(ctx context.Context, fromProject, sourceSessionKey, message string) (string, error) {
	agent, sessions, relaySessionKey, err := e.relayContextForSourceSessionKey(fromProject, sourceSessionKey)
	if err != nil {
		return "", err
	}
	session := sessions.GetOrCreateActive(relaySessionKey)

	if inj, ok := agent.(SessionEnvInjector); ok {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Read the wrapped cause to see whether registration, factory, or filesystem failed
2. Verify the agent CLI binary exists in PATH (cc-connect doctor can help)
3. Check that the agent type is compiled in (not excluded by no_* build tags)
4. Validate the workspace's agent config options in config.toml
5. Ensure the workspace state directory is writable by the process user

// startup check: agent binary reachable
bin := "claude" // from workspace agent config
if _, err := exec.LookPath(bin); err != nil {
    slog.Error("agent binary not in PATH", "bin", bin)
}

agent, sessions, err := e.getOrCreateWorkspaceAgent(workspace)
if err != nil {
    slog.Error("workspace agent unavailable",
        "workspace", workspace, "cause", errors.Unwrap(err))
    return nil, nil, "", fmt.Errorf("get relay workspace agent: %w", err)
}

When it happens

Trigger: e.getOrCreateWorkspaceAgent(workspace) returns an error during relay — the configured agent type for the workspace is not registered (excluded via build tag), the agent factory fails (bad options), or creating the SessionManager for the workspace fails (unwritable directory).

Common situations: Agent binary (claude, codex, gemini CLI) missing from PATH; workspace agent type removed from build via no_* tags; state directory for the workspace not writable; invalid agent options in the workspace config block.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• create workspace agent for %s: %w
• resolve relay workspace: %w
• workspace binding unavailable for source channel %q
• no workspace binding for source channel %q
• start relay session: %w

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