{"record":{"id":"e13a6237ba1bcf81","repo":"chenhg5/cc-connect","slug":"cloud-web-preview-ack-timeout-e13a62","errorCode":null,"errorMessage":"cloud_web: preview_ack timeout","messagePattern":"cloud_web: preview_ack timeout","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"platform/cloud-web/poll.go","lineNumber":286,"sourceCode":"\t}\n\treturn nil\n}\n\nfunc (t *pollTransport) waitPreviewAck(refID string, timeout time.Duration) (string, error) {\n\tch := make(chan string, 1)\n\tt.previewMu.Lock()\n\tt.previewRequests[refID] = ch\n\tt.previewMu.Unlock()\n\tdefer func() {\n\t\tt.previewMu.Lock()\n\t\tdelete(t.previewRequests, refID)\n\t\tt.previewMu.Unlock()\n\t}()\n\tselect {\n\tcase handle := <-ch:\n\t\treturn handle, nil\n\tcase <-time.After(timeout):\n\t\treturn \"\", fmt.Errorf(\"cloud_web: preview_ack timeout\")\n\t}\n}\n","sourceCodeStart":268,"sourceCodeEnd":289,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/platform/cloud-web/poll.go#L268-L289","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check logs for 'long poll error' entries — fix any persistent poll failures first, since acks ride the poll stream.","Increase the preview wait timeout (or the poll timeout_ms) to accommodate slow preview generation.","Verify the cloud-web server's preview service is healthy and emitting preview_ack events.","Restart the platform after fixing connectivity so pending preview state is reset."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// before requesting a preview, confirm the poll loop is healthy\n// (no repeated 'long poll error' entries in logs) and that the poll\n// endpoint authenticates:\nreq, _ := http.NewRequest(\"POST\", baseURL+\"/events\", strings.NewReader(\"{}\"))\nreq.Header.Set(\"Authorization\", \"Bearer \"+token)\nresp, err := http.DefaultClient.Do(req)\nif err == nil {\n    resp.Body.Close()\n    if resp.StatusCode != 200 {\n        return fmt.Errorf(\"poll stream unhealthy (%d); previews will time out\", resp.StatusCode)\n    }\n}","typeGuard":null,"tryCatchPattern":"handle, err := platform.RequestPreview(ctx, refID)\nif err != nil && strings.Contains(err.Error(), \"preview_ack timeout\") {\n    slog.Warn(\"preview ack not received via poll stream; retrying\", \"ref\", refID)\n    time.Sleep(time.Second)\n    handle, err = platform.RequestPreview(ctxWithLongerTimeout, refID)\n}","preventionTips":["Fix any persistent poll errors first — preview acks travel the poll stream","Give the preview timeout headroom over server-side preview latency","Confirm the server's preview pipeline emits preview_ack with matching ref_id","Restart the platform after connectivity fixes to clear stale pending state"],"tags":["timeout","preview","long-polling","async"],"backgroundTag":"request-timeout","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"}