chenhg5/cc-connect · error

cloud_web: preview_ack timeout

Error message

cloud_web: preview_ack timeout

What it means

A card preview request sent through the long-poll transport timed out waiting for the server's async 'preview_ack'. In poll mode the ack arrives via the long-poll events stream (or inline in the send response); if neither delivers an ack with the matching ref_id before the deadline, this error is returned and the pending entry is removed.

Source

Thrown at platform/cloud-web/poll.go:286

	}
	return nil
}

func (t *pollTransport) waitPreviewAck(refID string, timeout time.Duration) (string, error) {
	ch := make(chan string, 1)
	t.previewMu.Lock()
	t.previewRequests[refID] = ch
	t.previewMu.Unlock()
	defer func() {
		t.previewMu.Lock()
		delete(t.previewRequests, refID)
		t.previewMu.Unlock()
	}()
	select {
	case handle := <-ch:
		return handle, nil
	case <-time.After(timeout):
		return "", fmt.Errorf("cloud_web: preview_ack timeout")
	}
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Check logs for 'long poll error' entries — fix any persistent poll failures first, since acks ride the poll stream.
2. Increase the preview wait timeout (or the poll timeout_ms) to accommodate slow preview generation.
3. Verify the cloud-web server's preview service is healthy and emitting preview_ack events.
4. Restart the platform after fixing connectivity so pending preview state is reset.

// before requesting a preview, confirm the poll loop is healthy
// (no repeated 'long poll error' entries in logs) and that the poll
// endpoint authenticates:
req, _ := http.NewRequest("POST", baseURL+"/events", strings.NewReader("{}"))
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
if err == nil {
    resp.Body.Close()
    if resp.StatusCode != 200 {
        return fmt.Errorf("poll stream unhealthy (%d); previews will time out", resp.StatusCode)
    }
}

handle, err := platform.RequestPreview(ctx, refID)
if err != nil && strings.Contains(err.Error(), "preview_ack timeout") {
    slog.Warn("preview ack not received via poll stream; retrying", "ref", refID)
    time.Sleep(time.Second)
    handle, err = platform.RequestPreview(ctxWithLongerTimeout, refID)
}

When it happens

Trigger: waitPreviewAck's select expires because the server never generated/sent the preview_ack, the poll loop is broken (e.g. poll returning 401 in a retry loop per error 1007), the ack's ref_id didn't match, or the timeout is shorter than server-side preview generation.

Common situations: Long-poll stream stuck retrying on auth errors so acks can't flow; server-side preview service slow or down; misconfigured very small timeout_ms; connectivity outage between polls.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• cloud_web: preview_ack timeout
• bridge: preview_ack timeout
• wecom-ws: ack timeout
• %s timed out
• %s write timed out

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