chenhg5/cc-connect · error

matrix: connection lost

Error message

matrix: connection lost

What it means

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.

Source

Thrown at platform/matrix/matrix.go:842

	p.unavailableNotified = false
	p.mu.Unlock()

	if handler != nil {
		handler.OnPlatformReady(p)
	}
}

func (p *Platform) clearClient(gen uint64, client *mautrix.Client) {
	notify := false
	p.mu.Lock()
	if p.client == client && p.generation == gen {
		p.client = nil
		notify = !p.stopping
	}
	p.mu.Unlock()

	if notify {
		p.notifyUnavailable(fmt.Errorf("matrix: connection lost"))
	}
}

func (p *Platform) notifyUnavailable(err error) {
	var handler core.PlatformLifecycleHandler

	p.mu.Lock()
	if p.stopping || err == nil || p.unavailableNotified {
		p.mu.Unlock()
		return
	}
	p.unavailableNotified = true
	handler = p.lifecycleHandler
	p.mu.Unlock()

	if handler != nil {
		handler.OnPlatformUnavailable(p, err)
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Check preceding sync error logs for the root cause (network vs. auth)
2. Verify the homeserver URL is reachable (curl the /_matrix/client/versions endpoint)
3. Re-check the Matrix access token/credentials — regenerate if the token was invalidated
4. Ensure reconnect/backoff logic in runConnection is enabled so the client is restored automatically

// probe homeserver reachability
resp, err := http.Get(homeserver + "/_matrix/client/versions")
// err != nil => network outage; 401 => token invalid

platform.OnUnavailable(func(err error) {
    slog.Error("matrix unavailable", "err", err)
    // trigger backoff reconnect loop
})

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• redirected to unsupported image URL
• remote image host resolved to no usable IPs
• range chunk retries exhausted
• wecom-ws: ack timeout
• listen for Agy permission hooks: %w

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