{"record":{"id":"5acffa95259cda09","repo":"chenhg5/cc-connect","slug":"matrix-connection-lost","errorCode":null,"errorMessage":"matrix: connection lost","messagePattern":"matrix: connection lost","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"platform/matrix/matrix.go","lineNumber":842,"sourceCode":"\tp.unavailableNotified = false\n\tp.mu.Unlock()\n\n\tif handler != nil {\n\t\thandler.OnPlatformReady(p)\n\t}\n}\n\nfunc (p *Platform) clearClient(gen uint64, client *mautrix.Client) {\n\tnotify := false\n\tp.mu.Lock()\n\tif p.client == client && p.generation == gen {\n\t\tp.client = nil\n\t\tnotify = !p.stopping\n\t}\n\tp.mu.Unlock()\n\n\tif notify {\n\t\tp.notifyUnavailable(fmt.Errorf(\"matrix: connection lost\"))\n\t}\n}\n\nfunc (p *Platform) notifyUnavailable(err error) {\n\tvar handler core.PlatformLifecycleHandler\n\n\tp.mu.Lock()\n\tif p.stopping || err == nil || p.unavailableNotified {\n\t\tp.mu.Unlock()\n\t\treturn\n\t}\n\tp.unavailableNotified = true\n\thandler = p.lifecycleHandler\n\tp.mu.Unlock()\n\n\tif handler != nil {\n\t\thandler.OnPlatformUnavailable(p, err)\n\t}","sourceCodeStart":824,"sourceCodeEnd":860,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/platform/matrix/matrix.go#L824-L860","documentation":"clearClient emits \"matrix: connection lost\" via notifyUnavailable when the long-running Matrix sync loop (runConnection) exits while the platform is not intentionally stopping. It signals that the persistent connection to the homeserver was dropped and p.client has been set to nil. Lifecycle handlers are notified so the engine/platform can react to the outage.","triggerScenarios":"runConnection's sync loop returns an error or exits (network failure, homeserver outage, auth token invalidation) while p.stopping is false, so clearClient sets p.client = nil and fires notifyUnavailable with this error.","commonSituations":"Homeserver restart or maintenance window; local network interruption (WiFi drop, VPN disconnect); Matrix access token revoked or expired causing sync to fail permanently; firewall idle-timeout killing the long-poll sync connection.","solutions":["Check preceding sync error logs for the root cause (network vs. auth)","Verify the homeserver URL is reachable (curl the /_matrix/client/versions endpoint)","Re-check the Matrix access token/credentials — regenerate if the token was invalidated","Ensure reconnect/backoff logic in runConnection is enabled so the client is restored automatically"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// probe homeserver reachability\nresp, err := http.Get(homeserver + \"/_matrix/client/versions\")\n// err != nil => network outage; 401 => token invalid","typeGuard":null,"tryCatchPattern":"platform.OnUnavailable(func(err error) {\n    slog.Error(\"matrix unavailable\", \"err\", err)\n    // trigger backoff reconnect loop\n})","preventionTips":["Enable exponential backoff reconnect in runConnection","Monitor homeserver reachability with a health check","Rotate access tokens before expiry and alert on repeated sync failures"],"tags":["matrix","connection-lost","sync","network"],"backgroundTag":"connection-lost","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}