cloudflare/cloudflared · error

failed to build quick tunnel request

Error message

failed to build quick tunnel request

What it means

RunQuickTunnel fails while constructing the HTTP POST request to the quick-tunnel service (`<quick-service>/tunnel`). This happens when http.NewRequest cannot build a request, typically because the quick-service URL is malformed. The error wraps the underlying cause with this message.

Source

Thrown at cmd/cloudflared/tunnel/quick_tunnel.go:66

	allowedMail := sc.c.StringSlice(flags.AllowedMail)
	isProtected := len(allowedMail) > 0

	client := http.Client{
		Transport: &http.Transport{
			TLSHandshakeTimeout:   httpTimeout,
			ResponseHeaderTimeout: httpTimeout,
		},
		Timeout: httpTimeout,
	}

	reqBody, err := buildQuickTunnelRequestBody(isProtected)
	if err != nil {
		return errors.Wrap(err, "failed to build quick tunnel request body")
	}

	req, err := http.NewRequest(http.MethodPost, fmt.Sprintf("%s/tunnel", sc.c.String("quick-service")), bytes.NewReader(reqBody))
	if err != nil {
		return errors.Wrap(err, "failed to build quick tunnel request")
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("User-Agent", buildInfo.UserAgent())

	resp, err := client.Do(req)
	if err != nil {
		return errors.Wrap(err, "failed to request quick Tunnel")
	}
	defer func() { _ = resp.Body.Close() }()

	// This will read the entire response into memory so we can print it in case of error
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return errors.Wrap(err, "failed to read quick-tunnel response")
	}

	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		var data QuickTunnelResponse

View on GitHub (pinned to 2253eeeb25)

Solutions

  1. Check the `quick-service` config value for typos and ensure it is a valid absolute http(s) URL
  2. Revert to the default quick-service URL by removing the override from config/flags
  3. Look at the wrapped inner error (printed by errors.Wrap) for the exact URL parse failure
  4. Upgrade cloudflared in case of a packaged default-value corruption

Example fix

// before
quick-service: "trycloudflare.com"   // missing scheme
// after
quick-service: "https://api.trycloudflare.com"
Defensive patterns

Strategy: validation

Validate before calling

qs := sc.c.String("quick-service")
if u, err := url.Parse(qs); err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid quick-service URL: %q", qs)
}

Prevention

When it happens

Trigger: http.NewRequest returns an error for the POST to `sc.c.String("quick-service")+"/tunnel"`, e.g. when the `quick-service` config flag is set to an unparseable URL.

Common situations: Users set a custom `quick-service` URL in their config file or via environment override with a typo, unsupported scheme, or invalid characters; default value is normally valid so this is rare.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/15ea80c50018e792. Report an issue: GitHub.