chenhg5/cc-connect · error

cloud_web: parse register_ack: %w

Error message

cloud_web: parse register_ack: %w

What it means

parseRegisterAck wraps any JSON unmarshal failure of the server's register_ack frame with this prefixed error. The cloud-web transport requires every WebSocket connection to start with a valid register_ack JSON message; if the first frame is not decodable JSON into wireRegisterAck, the connection is closed and this error propagates to register/connectOnce. It means the remote cloud-web server sent malformed or unexpected bytes as its handshake acknowledgment.

Source

Thrown at platform/cloud-web/protocol.go:197

}

func buildRegisterPayload(name, project, transport string) wireRegister {
	return wireRegister{
		Type:      "register",
		Platform:  name,
		Client:    "cc-connect",
		Project:   project,
		Transport: transport,
		Metadata: map[string]any{
			"protocol_version": protocolVersion,
		},
	}
}

func parseRegisterAck(raw []byte) (map[string]bool, error) {
	var ack wireRegisterAck
	if err := json.Unmarshal(raw, &ack); err != nil {
		return nil, fmt.Errorf("cloud_web: parse register_ack: %w", err)
	}
	if ack.Type != "register_ack" {
		return nil, fmt.Errorf("cloud_web: expected register_ack, got %q", ack.Type)
	}
	if !ack.OK {
		if ack.Error != "" {
			return nil, fmt.Errorf("cloud_web: register rejected: %s", ack.Error)
		}
		return nil, fmt.Errorf("cloud_web: register rejected")
	}
	if len(ack.Capabilities) == 0 {
		return defaultCapabilities(), nil
	}
	return capabilitySet(ack.Capabilities), nil
}

func decodeImages(items []wireImage) []core.ImageAttachment {
	var out []core.ImageAttachment

View on GitHub (pinned to 4000b2338a)

Solutions

1. Verify wsURL in config points at the cloud-web WebSocket endpoint (correct scheme, host, port, path), not an HTTP page or wrong service
2. Check what the server actually sends as its first frame (e.g. wscat or server logs); fix the server-side handshake or version mismatch
3. Confirm no reverse proxy/auth middleware is intercepting the WebSocket upgrade and returning HTML or plain text
4. Check network/proxy compression or TLS termination that could corrupt the frame; inspect the wrapped underlying error (%w) for the exact JSON failure

Example fix

// before (server not yet upgraded, sends old handshake)
caps, err := parseRegisterAck(raw)
// after (log the raw frame to diagnose, then fix server/client version alignment)
if err != nil {
    slog.Error("cloud_web: bad register_ack", "raw", string(raw), "err", err)
}

// Validate the endpoint before dialing
u, err := url.Parse(cfg.WSURL)
if err != nil || u.Scheme != "ws" && u.Scheme != "wss" {
    return fmt.Errorf("invalid cloud-web wsURL %q: %w", cfg.WSURL, err)
}

// Treat wrapped json error as fatal config/protocol issue; log raw frame
if err := register(ctx); err != nil {
    if strings.Contains(err.Error(), "parse register_ack") {
        slog.Error("cloud-web handshake returned non-JSON frame; check wsURL/proxy", "err", err)
        return err
    }
}

When it happens

Trigger: json.Unmarshal(raw, &ack) fails because the first WebSocket message after dial is not valid JSON, is an HTML error page from a reverse proxy, is binary, is empty (EOF), or is a valid JSON type other than the expected object shape.

Common situations: Connecting to an HTTP(S) URL instead of a ws(s):// URL so the proxy returns an HTML 4xx/5xx page; a load balancer or auth layer intercepting the upgrade and returning plain text; wrong port or path in config so a different service answers; server closes the connection immediately (empty frame); protocol version mismatch where the server sends a different handshake message first.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• cloud_web: expected register_ack, got %q
• cloud_web: ws_url or base_url is required for websocket tran
• cloud_web: register rejected: %s
• cloud_web: register rejected
• parse ws url: %w

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