cloudflare/cloudflared · error

REST request failed

Error message

REST request failed

What it means

This error wraps a transport-level failure in RESTClient.CreateTunnel (cfapi/tunnel.go:106). The POST to the accountLevel tunnelstore endpoint failed inside r.sendRequest — meaning http.Client.Do returned an error (DNS failure, connection refused/reset, TLS problem, timeout, or a JSON serialization failure of the request body is handled separately, so this is network-level). The tunnel was not created; the API never returned a response.

Source

Thrown at cfapi/tunnel.go:106

func (cp CleanupParams) encode() string {
	return cp.queryParams.Encode()
}

func (r *RESTClient) CreateTunnel(name string, tunnelSecret []byte) (*TunnelWithToken, error) {
	if name == "" {
		return nil, errors.New("tunnel name required")
	}
	if _, err := uuid.Parse(name); err == nil {
		return nil, errors.New("you cannot use UUIDs as tunnel names")
	}
	body := &newTunnel{
		Name:         name,
		TunnelSecret: tunnelSecret,
	}

	resp, err := r.sendRequest("POST", r.baseEndpoints.accountLevel, body)
	if err != nil {
		return nil, errors.Wrap(err, "REST request failed")
	}
	defer resp.Body.Close()

	switch resp.StatusCode {
	case http.StatusOK:
		var tunnel TunnelWithToken
		if serdeErr := parseResponse(resp.Body, &tunnel); serdeErr != nil {
			return nil, serdeErr
		}
		return &tunnel, nil
	case http.StatusConflict:
		return nil, ErrTunnelNameConflict
	}

	return nil, r.statusCodeToError("create tunnel", resp)
}

func (r *RESTClient) GetTunnel(tunnelID uuid.UUID) (*Tunnel, error) {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Verify connectivity to the API host (curl -v https://api.cloudflare.com) and resolve network/proxy/firewall problems
2. Check the wrapped cause inside the error for the concrete net/http reason (timeout vs refused vs TLS)
3. Set/fix HTTPS_PROXY if behind a corporate proxy; ensure its CA is trusted
4. Retry with exponential backoff for transient failures; check api.cloudflare.com status for incidents

Example fix

// before
tunnel, err := client.CreateTunnel(name, secret)
if err != nil { return err }
// after
tunnel, err := client.CreateTunnel(name, secret)
if err != nil {
    log.Warn().Err(err).Msg("create tunnel request failed, retrying")
    return retryWithBackoff(3, func() error { _, err = client.CreateTunnel(name, secret); return err })
}

// Go: preflight reachability + non-empty inputs before CreateTunnel
func preflight(host, name string, secret []byte) error {
    if name == "" || len(secret) == 0 { return errors.New("name and secret required") }
    conn, err := net.DialTimeout("tcp", host+":443", 5*time.Second)
    if err != nil { return err }
    _ = conn.Close()
    return nil
}

func isTransportError(err error) bool {
    var netErr net.Error
    return errors.As(err, &netErr) || errors.As(err, new(*net.OpError))
}

tunnel, err := client.CreateTunnel(name, secret)
if err != nil && isTransportError(err) {
    return retryWithBackoff(3, 2*time.Second, func() error {
        tunnel, err = client.CreateTunnel(name, secret)
        return err
    })
}

When it happens

Trigger: Calling CreateTunnel when the HTTP POST cannot complete: no connectivity to the Cloudflare API host, proxy/firewall blocking, TLS interception with untrusted certs, request timeout on slow networks, or an invalid base endpoint URL passed to NewRESTClient.

Common situations: CI runners without egress to api.cloudflare.com; corporate proxies requiring HTTPS_PROXY; offline local development; misconfigured endpoint override in tests; long request timing out due to defaultTimeout on saturated links.

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

• quick tunnel provisioning failed with status %d: %s
• quick tunnel provisioning failed: %s
• unable to check for update: %d
• SRV record %v had no IPs
• failed to find Access application at %s

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