cloudflare/cloudflared · error

failed to request quick Tunnel

Error message

failed to request quick Tunnel

What it means

The HTTP request that provisions a quick (trycloudflare) tunnel failed at the transport level — cloudflared could not complete the POST to the quick-tunnel API. errors.Wrap attaches the underlying net/http error (DNS, TLS, timeout, connection refused).

Source

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

		},
		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
		if err := json.Unmarshal(respBody, &data); err == nil && len(data.Errors) > 0 {
			return fmt.Errorf("quick tunnel provisioning failed with status %d: %s", resp.StatusCode, formatQuickTunnelErrors(data.Errors))
		}
		return fmt.Errorf("quick tunnel provisioning failed with status %d: %s", resp.StatusCode, string(respBody))
	}

	var data QuickTunnelResponse

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Verify outbound network connectivity (e.g. `curl -v https://api.trycloudflare.com/tunnel`)
2. Check proxy/firewall rules and set HTTPS_PROXY if a proxy is required
3. Retry after transient network issues; cloudflared retries connections but provisioning is a single request
4. Inspect the wrapped error for DNS vs TLS vs timeout to pinpoint the cause

Example fix

// before
$ cloudflared tunnel --url http://localhost:8080   # on airgapped host
// after
$ export HTTPS_PROXY=http://corp-proxy:3128
$ cloudflared tunnel --url http://localhost:8080

// preflight
if _, err := net.LookupHost("api.trycloudflare.com"); err != nil {
    return fmt.Errorf("cannot resolve quick-tunnel API host: %w", err)
}

if err := runQuickTunnel(ctx, ...); err != nil {
    var nerr net.Error
    if errors.As(err, &nerr) && nerr.Timeout() {
        // backoff and retry provisioning
    }
    return err
}

When it happens

Trigger: client.Do(req) returns a non-nil error when POSTing to `<quick-service>/tunnel` during `cloudflared tunnel --url ...` quick-tunnel setup.

Common situations: No internet access or blocked outbound HTTPS; corporate proxy/firewall dropping the request; DNS failures resolving the quick-service host; TLS interception appliances; transient network outage.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• unable to check for update: %d
• failed to build quick tunnel request
• failed to read quick-tunnel response
• Invalid CIDR supplied for %s
• invalid connection override: %s

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