multica-ai/multica · error

list agents: %w

Error message

list agents: %w

What it means

runAgentList wraps any failure of client.GetJSON against GET /api/agents (with optional workspace_id and include_archived query params). The %w chain preserves the underlying transport/HTTP error, so the real cause — DNS, TLS, 4xx/5xx, auth rejection — is one unwrap away.

Source

Thrown at server/cmd/multica/cmd_agent.go:539

			return err
		}
	}

	ctx, cancel := cli.APIContext(context.Background())
	defer cancel()

	var agents []map[string]any
	params := url.Values{}
	params.Set("workspace_id", client.WorkspaceID)
	if v, _ := cmd.Flags().GetBool("include-archived"); v {
		params.Set("include_archived", "true")
	}
	path := "/api/agents"
	if len(params) > 0 {
		path += "?" + params.Encode()
	}
	if err := client.GetJSON(ctx, path, &agents); err != nil {
		return fmt.Errorf("list agents: %w", err)
	}

	output, _ := cmd.Flags().GetString("output")
	if output == "json" {
		return cli.PrintJSON(os.Stdout, agents)
	}

	headers := []string{"ID", "NAME", "STATUS", "RUNTIME", "ARCHIVED"}
	rows := make([][]string, 0, len(agents))
	for _, a := range agents {
		archived := ""
		if v := strVal(a, "archived_at"); v != "" {
			archived = "yes"
		}
		rows = append(rows, []string{
			strVal(a, "id"),
			strVal(a, "name"),
			strVal(a, "status"),

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Unwrap the error and check the HTTP status: 401/403 → token problem, 404 → workspace/URL problem, connection refused → wrong server_url.
2. Verify reachability: curl the /api/agents endpoint with the same token and server URL.
3. Confirm MULTICA_WORKSPACE_ID matches an existing workspace.
4. Retry once if the failure was a transient 5xx/network blip.

Example fix

# before
multica agent list  # -> list agents: Get "https://...": connection refused

# after: point at the live server
multica config set server_url https://app.multica.dev
multica agent list

// Cheap preflight before the call: verify URL shape and token presence.
if u, err := url.Parse(serverURL); err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid server URL %q", serverURL)
}
if token == "" {
    return fmt.Errorf("MULTICA_TOKEN not set")
}

var agents []map[string]any
err := client.GetJSON(ctx, path, &agents)
if err != nil {
    var statusErr *cli.HTTPStatusError // or inspect the wrapped error's code
    if errors.As(err, &statusErr) && statusErr.Code >= 500 && statusErr.Code < 600 {
        // transient: retry with backoff
        return retryWithBackoff(ctx, func() error {
            return client.GetJSON(ctx, path, &agents)
        })
    }
    return fmt.Errorf("list agents: %w", err)
}

When it happens

Trigger: The API client cannot reach the server URL, the token is rejected (401/403), the workspace_id param references an unknown workspace (4xx), or the server returns a 5xx; also JSON decode failures if the response body is not the expected shape.

Common situations: Wrong/stale server_url pointing at a dead instance; expired or human-scoped token where a mat_ token is required; workspace deleted or ID typo; network egress blocked from containers.

Related errors

• get agent: %w
• get source agent: %w
• copy agent: %w
• list agent mcp servers: %w
• add agent mcp server: %w

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