multica-ai/multica · error

fetch agents: %w

Error message

fetch agents: %w

What it means

resolveAgent wraps any failure of the GET /api/agents?workspace_id=<id> request (via client.GetJSON) with 'fetch agents: %w'. The wrapped error contains the real cause: connection refused, 401/403 auth failure, 404, 5xx, or a JSON decode failure of the response body.

Source

Thrown at server/cmd/multica/cmd_autopilot.go:788

// ---------------------------------------------------------------------------

// uuidRegexp matches a canonical UUID (8-4-4-4-12 hex).
var uuidRegexp = regexp.MustCompile(`^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`)

// resolveAgent accepts either a UUID or an agent name (case-insensitive substring)
// and returns the agent's UUID. Errors on no match or ambiguous match.
func resolveAgent(ctx context.Context, client *cli.APIClient, nameOrID string) (string, error) {
	if uuidRegexp.MatchString(nameOrID) {
		return nameOrID, nil
	}
	if client.WorkspaceID == "" {
		return "", fmt.Errorf("workspace ID is required to resolve agents; use --workspace-id or set MULTICA_WORKSPACE_ID")
	}

	var agents []map[string]any
	agentPath := "/api/agents?" + url.Values{"workspace_id": {client.WorkspaceID}}.Encode()
	if err := client.GetJSON(ctx, agentPath, &agents); err != nil {
		return "", fmt.Errorf("fetch agents: %w", err)
	}

	nameLower := strings.ToLower(nameOrID)
	type match struct{ ID, Name string }
	var matches []match
	for _, a := range agents {
		aName := strVal(a, "name")
		if strings.Contains(strings.ToLower(aName), nameLower) {
			matches = append(matches, match{ID: strVal(a, "id"), Name: aName})
		}
	}

	switch len(matches) {
	case 0:
		return "", fmt.Errorf("no agent found matching %q", nameOrID)
	case 1:
		return matches[0].ID, nil
	default:

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Read the wrapped error: a 401/403 means re-authenticate; connection refused means the server URL/port is wrong or the server is down.
2. Verify connectivity: `multica config get server_url` and curl the /api/agents endpoint with the same credentials.
3. Confirm the workspace still exists and the current user has access to it.

# preflight the endpoint the resolver will hit
curl -sf -H "Authorization: Bearer $TOKEN" "$SERVER_URL/api/agents?workspace_id=$WS" -o /dev/null \
  || { echo "agents endpoint unreachable or unauthorized" >&2; exit 2; }

err := cmd.Run()
if err != nil && strings.Contains(err.Error(), "fetch agents") {
    if isTransient(err) { // connection refused, 502/503, timeout
        time.Sleep(backoff)
        err = cmd.Run()
    }
}

When it happens

Trigger: Server down or wrong server_url in CLI config; expired/invalid auth credentials; the workspace_id is valid format but inaccessible to the current user; proxy or TLS interception breaking the request.

Common situations: Local dev server not running when the CLI points at localhost; token expired after long idle; server_url pointing at a stale deployment; workspace deleted or user removed from it.

Related errors

• list agents: %w
• get agent: %w
• read chat: %w
• create property: %w
• update property: %w

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/edee2ce0e3d23fdd. Report an issue: GitHub.