larksuite/cli · error

connection check: %w

Error message

connection check: %w

What it means

CheckRemoteConnections performs a preflight GET to /open-apis/event/v1/connection to count active WebSocket long-connection instances for the app. When the underlying APIClient.CallAPI transport/network call fails (unreachable host, auth rejection, timeout, non-2xx handled at the transport layer), the error is wrapped as 'connection check: %w' so the caller sees the preflight context plus the root cause. It deliberately returns count 0 with the error, since the check failed rather than being verified as zero.

Source

Thrown at internal/event/consume/remote_preflight.go:20

// SPDX-License-Identifier: MIT

package consume

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/larksuite/cli/internal/event"
)

type APIClient = event.APIClient

// CheckRemoteConnections returns the count of active WebSocket connections for this app.
func CheckRemoteConnections(ctx context.Context, client APIClient) (int, error) {
	raw, err := client.CallAPI(ctx, "GET", "/open-apis/event/v1/connection", nil)
	if err != nil {
		return 0, fmt.Errorf("connection check: %w", err)
	}
	var result struct {
		Code int    `json:"code"`
		Msg  string `json:"msg"`
		Data struct {
			OnlineInstanceCnt int `json:"online_instance_cnt"`
		} `json:"data"`
	}
	if err := json.Unmarshal(raw, &result); err != nil {
		return 0, fmt.Errorf("connection check: decode: %w (body=%s)", err, truncateForError(raw))
	}
	// Distinguish "verified zero" from "check failed" — non-zero code decodes Cnt=0.
	if result.Code != 0 {
		return 0, fmt.Errorf("connection check: api error code=%d msg=%q", result.Code, result.Msg)
	}
	return result.Data.OnlineInstanceCnt, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Run the same GET /open-apis/event/v1/connection with curl using the app's credentials to confirm the endpoint is reachable.
2. Check that the app credentials (app_id/app_secret or token) are valid and not expired; refresh the token.
3. Verify network/proxy/DNS settings allow HTTPS to the Lark/Feishu open domain.
4. Unwrap with errors.Unwrap or errors.As to read the root cause and apply the matching transport fix.

// Preflight reachability check before invoking CheckRemoteConnections
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, http.MethodGet,
	baseURL+"/open-apis/event/v1/connection", nil)
if _, err := http.DefaultClient.Do(req); err != nil {
	// abort early: network/credentials are broken
}

cnt, err := consume.CheckRemoteConnections(ctx, client)
if err != nil {
	var apiErr *errs.APIError // or the concrete client error type
	if errors.As(err, &apiErr) {
		// inspect status/code; retry only transient categories
	}
	if !isRetryable(err) { return fmt.Errorf("preflight aborted: %w", err) }
}

When it happens

Trigger: Any CallAPI error on GET /open-apis/event/v1/connection during remote preflight: network unreachable, DNS failure, TLS error, HTTP timeout, invalid tenant access token, or 4xx/5xx responses surfaced by the client's error path.

Common situations: Offline or restricted CI environments running a consumer that dials the bus, expired or missing app credentials, wrong domain/base-URL configuration, corporate proxy blocking the endpoint, firewall dropping outbound HTTPS.

Related errors

• app registration failed: HTTP %d – response not JSON
• Device authorization failed: read body: %v
• failed to read response body in security transport: %w
• response parse error: %w (body: %s)
• failed to read TAT response: %w

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/6c39ebfbc0f5ddb2. Report an issue: GitHub.