Tencent/WeKnora · error

failed to execute Metaso request: %w

Error message

failed to execute Metaso request: %w

What it means

Returned by MetasoProvider.Search when p.client.Do(req) fails, i.e. the HTTP request could not be completed at the transport level. This wraps DNS failures, connection refused/reset, TLS errors, and context cancellation or deadline exceeded. Since Metaso requires the API call to succeed, the search aborts with the underlying cause wrapped via %w.

Source

Thrown at internal/infrastructure/web_search/metaso.go:104

	body, err := json.Marshal(metasoSearchRequest{
		Query: query, Scope: p.scope, Size: maxResults,
		IncludeSummary: true, IncludeRawContent: false, ConciseSnippet: true,
	})
	if err != nil {
		return nil, fmt.Errorf("failed to marshal Metaso request: %w", err)
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, p.baseURL, bytes.NewReader(body))
	if err != nil {
		return nil, fmt.Errorf("failed to create Metaso request: %w", err)
	}
	req.Header.Set("Authorization", "Bearer "+p.apiKey)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	logger.Infof(ctx, "[WebSearch][Metaso] query=%q maxResults=%d scope=%s", query, maxResults, p.scope)
	resp, err := p.client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("failed to execute Metaso request: %w", err)
	}
	defer resp.Body.Close()
	respBody, err := readMetasoResponseBody(resp.Body)
	if err != nil {
		return nil, err
	}
	if resp.StatusCode != http.StatusOK {
		return nil, metasoHTTPError(resp.StatusCode, respBody)
	}

	var response metasoSearchResponse
	if err := json.Unmarshal(respBody, &response); err != nil {
		return nil, fmt.Errorf("failed to unmarshal Metaso response: %w", err)
	}
	results := make([]*types.WebSearchResult, 0, len(response.Webpages))
	for _, item := range response.Webpages {
		if strings.TrimSpace(item.Title) == "" && strings.TrimSpace(item.Link) == "" {
			continue

View on GitHub (pinned to 988cbb0330)

Solutions

1. Unwrap the error: check errors.Is(err, context.DeadlineExceeded) for timeouts, or use net.Error.Timeout() and *url.Error to identify DNS/connect/TLS causes.
2. Verify basic connectivity to the Metaso endpoint (curl the base URL) and DNS resolution from the host running the app.
3. Increase the context/client timeout if the deadline is shorter than Metaso's response time, and retry with backoff for transient failures.
4. Check proxy/firewall settings (HTTP_PROXY/HTTPS_PROXY) and TLS interception certificates.
5. Confirm the base URL host/port is correct if you run a custom endpoint.

Example fix

// before: no timeout differentiation or retry
resp, err := p.client.Do(req)
if err != nil { return nil, err }

// after: timeout-aware retry
var resp *http.Response
for attempt := 0; attempt < 3; attempt++ {
    resp, err = p.client.Do(req)
    if err == nil { break }
    var ne net.Error
    if errors.As(err, &ne) && ne.Timeout() {
        time.Sleep(time.Duration(attempt+1) * time.Second)
        continue
    }
    break
}
if err != nil { return nil, fmt.Errorf("failed to execute Metaso request: %w", err) }

ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

// pre-flight reachability check at startup:
if err := net.DialTimeout("tcp", "api.metaso.cn:443", 5*time.Second); err != nil {
    log.Printf("warning: Metaso endpoint unreachable at startup: %v", err)
}

resp, err := p.client.Do(req)
if err != nil {
    var ne net.Error
    switch {
    case errors.As(err, &ne) && ne.Timeout():
        return nil, fmt.Errorf("metaso request timed out, retry advised: %w", err)
    case errors.Is(err, context.Canceled):
        return nil, err // caller canceled — do not retry
    default:
        return nil, fmt.Errorf("transient network failure: %w", err)
    }
}

When it happens

Trigger: Search (internal/infrastructure/web_search/metaso.go:104): client.Do returns an error — network unreachable, DNS resolution failure for the Metaso host, connection refused (server down/wrong port), TLS handshake failure, or ctx deadline exceeded/canceled mid-request.

Common situations: No internet or DNS outage; corporate firewall/proxy blocking api.metaso.cn; wrong baseURL host; short context timeout cutting off a slow response; certificate issues behind a TLS-intercepting proxy.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• failed to execute request: %w
• fetch failed: %w
• HTTP GET: %w
• HTTP request: %w
• service unreachable: %w

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/708bd69b7f94de73. Report an issue: GitHub.