{"record":{"id":"acb70484cbac5702","repo":"siyuan-note/siyuan","slug":"failed-to-connect-cloud-server","errorCode":null,"errorMessage":"failed to connect cloud server","messagePattern":"failed to connect cloud server","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/cloud_service.go","lineNumber":40,"sourceCode":"\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"regexp\"\n\t\"strconv\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/88250/gulu\"\n\t\"github.com/88250/lute/parse\"\n\t\"github.com/siyuan-note/httpclient\"\n\t\"github.com/siyuan-note/logging\"\n\t\"github.com/siyuan-note/siyuan/kernel/conf\"\n\t\"github.com/siyuan-note/siyuan/kernel/task\"\n\t\"github.com/siyuan-note/siyuan/kernel/util\"\n)\n\nvar ErrFailedToConnectCloudServer = errors.New(\"failed to connect cloud server\")\n\nfunc CloudChatGPT(msg string, contextMsgs []string) (ret string, stop bool, err error) {\n\tif nil == Conf.GetUser() {\n\t\treturn\n\t}\n\n\tpayload := map[string]any{}\n\tvar messages []map[string]any\n\tfor _, contextMsg := range contextMsgs {\n\t\tmessages = append(messages, map[string]any{\n\t\t\t\"role\":    \"user\",\n\t\t\t\"content\": contextMsg,\n\t\t})\n\t}\n\tmessages = append(messages, map[string]any{\n\t\t\"role\":    \"user\",\n\t\t\"content\": msg,\n\t})","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/model/cloud_service.go#L22-L58","documentation":"Sentinel error ErrFailedToConnectCloudServer, returned by every cloud-facing function (CloudChatGPT, StartFreeTrial, DeactivateUser, SetCloudBlockReminder, LoadUploadToken, cloud shorthand ops) when the underlying httpclient POST to util.GetCloudServer() fails at the transport layer or returns a network error. It abstracts away the raw HTTP client error into a single recognizable cause.","triggerScenarios":"The HTTP request to the SiYuan cloud server (liuyun.io / ld246.com) fails: DNS resolution error, connection refused/reset, TLS handshake failure, or a timeout from NewCloudRequest30s (30s). The error is set after logging.LogErrorf logs the raw cause.","commonSituations":"User is offline or behind a proxy/firewall blocking the cloud domain; cloud server is temporarily down; DNS misconfigured; corporate network intercepts TLS; the 30-second timeout is exceeded on a slow link.","solutions":["Check network connectivity and that the cloud server domain is reachable (curl the /apis endpoint).","Verify proxy/TLS settings are not blocking the connection; allow the cloud domain through any firewall.","Retry the operation after a short delay, since the cause is often transient.","If persistent, check SiYuan cloud status and the user's region (mainland China uses ld246.com)."],"exampleFix":"// before\nret, stop, err := CloudChatGPT(msg, ctx)\nif err != nil { return err }\n\n// after\nret, stop, err := CloudChatGPT(msg, ctx)\nif errors.Is(err, model.ErrFailedToConnectCloudServer) {\n    // surface a friendly 'network unavailable' message, offer retry\n}\nif err != nil { return err }","handlingStrategy":"retry","validationCode":"// Quick reachability check before a cloud call\nfunc cloudReachable() bool {\n    c := http.Client{Timeout: 5 * time.Second}\n    resp, err := c.Get(util.GetCloudServer() + \"/apis/siyuan/version\")\n    if err != nil { return false }\n    defer resp.Body.Close()\n    return resp.StatusCode == http.StatusOK\n}","typeGuard":"func isConnectionError(err error) bool { return errors.Is(err, model.ErrFailedToConnectCloudServer) }","tryCatchPattern":"var lastErr error\nfor attempt := 0; attempt < 3; attempt++ {\n    _, _, err := model.CloudChatGPT(msg, ctx)\n    if err == nil { break }\n    if !errors.Is(err, model.ErrFailedToConnectCloudServer) { lastErr = err; break }\n    lastErr = err\n    time.Sleep(time.Duration(1<<attempt) * time.Second)\n}","preventionTips":["Confirm network/cloud reachability before cloud operations.","Allow the cloud domain through firewalls/proxies.","Surface a friendly offline message and offer retry rather than failing silently."],"tags":["cloud","network","connection","retry","cloud-service"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}