chenhg5/cc-connect · error

cloud_web: preview_ack timeout

Error message

cloud_web: preview_ack timeout

What it means

A card preview was requested through the gateway transport and the transport waited for the cloud-web server to deliver an async 'preview_ack' event (routed via the webhook listener), but no ack arrived before the timeout elapsed. The pending ref_id is cleaned up and a handle is not produced, so the preview cannot be finalized.

Source

Thrown at platform/cloud-web/gateway.go:316

	}
	return nil
}

func (t *gatewayTransport) 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")
	}
}

// previewWaiter is implemented by transports that support async preview_ack.
type previewWaiter interface {
	waitPreviewAck(refID string, timeout time.Duration) (string, error)
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Check gateway logs for incoming webhook POSTs; 401s mean fix the shared token so acks authenticate.
2. Verify public_url is externally reachable from the cloud-web server (curl the webhook URL from the server host).
3. Increase the preview timeout so slow server-side preview generation completes.
4. If the gateway listener failed to start (error 'gateway listen'), fix that first — acks are delivered through it.

// before requesting a preview, confirm the webhook is reachable from the server
// (run on the cloud-web server host):
// curl -s -o /dev/null -w '%{http_code}' -X POST -H 'Authorization: Bearer <token>' https://cc-connect-host:8099/cloud-web/webhook
// expect 200 (or 400 for empty body), not 000/401

handle, err := platform.RequestPreview(ctx, refID)
if err != nil && strings.Contains(err.Error(), "preview_ack timeout") {
    slog.Warn("preview ack timed out; retrying once with longer deadline", "ref", refID)
    handle, err = platform.RequestPreview(ctxWithLongerTimeout, refID)
}

When it happens

Trigger: waitPreviewAck's select times out: the server never sent preview_ack, it was delayed beyond the timeout, the ack was dropped (webhook unreachable, auth failing so webhookHandler returns 401, or the gateway listener from error 1000 never came up), or the ack's ref_id did not match.

Common situations: Inbound webhook URL not reachable from the server (firewall/NAT, wrong public_url) so acks never arrive; Authorization token mismatch causing 401 on every webhook POST; preview generation genuinely slow server-side; timeout configured too aggressively.

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
• cloud_web: transport does not support preview_ack
• read register_ack: %w
• cloud_web: preview_ack timeout

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