What causes "quick tunnel provisioning failed" in cloudflare/cloudflared?

Retry the command; provisioning failures are often transient.

quick tunnel provisioning failed

Error message

quick tunnel provisioning failed

What it means

RunQuickTunnel provisions an ephemeral Quick Tunnel via the Cloudflare API. When the API response reports no specific errors but data.Success is false, cloudflared cannot extract a detailed reason and returns the generic "quick tunnel provisioning failed". It indicates the provisioning request failed server-side without a structured error entry.

Source

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

		}
		return fmt.Errorf("quick tunnel provisioning failed with status %d: %s", resp.StatusCode, string(respBody))
	}

	var data QuickTunnelResponse
	if err := json.Unmarshal(respBody, &data); err != nil {
		respString := string(respBody)
		fields := map[string]interface{}{"status_code": resp.Status}
		sc.log.Err(err).Fields(fields).Msgf("Error unmarshaling QuickTunnel response: %s", respString)
		return errors.Wrap(err, "failed to unmarshal quick Tunnel")
	}

	// TODO(TUN-10791): Add CLI-level coverage that provisioning errors are logged to users.
	if len(data.Errors) > 0 {
		return fmt.Errorf("quick tunnel provisioning failed: %s", formatQuickTunnelErrors(data.Errors))
	}

	if !data.Success {
		return errors.New("quick tunnel provisioning failed")
	}

	tunnelID, err := uuid.Parse(data.Result.ID)
	if err != nil {
		return errors.Wrap(err, "failed to parse quick Tunnel ID")
	}

	credentials := connection.Credentials{
		AccountTag:   data.Result.AccountTag,
		TunnelSecret: data.Result.Secret,
		TunnelID:     tunnelID,
	}

	url := data.Result.Hostname
	if !strings.HasPrefix(url, "https://") {
		url = "https://" + url
	}

View on GitHub (pinned to 2253eeeb25)

Solutions

Retry the command; provisioning failures are often transient.
Check the Cloudflare status page for incidents affecting tunnel provisioning.
Ensure no proxy/TLS-intercepting appliance is altering the API response; try from a different network.
Fall back to a Named Tunnel (`cloudflared tunnel create`) which gives clearer API errors.

Defensive patterns

Strategy: retry

Try / catch

err := runQuickTunnel();
if err != nil && strings.Contains(err.Error(), "quick tunnel provisioning failed") {
    time.Sleep(2 * time.Second)
    // retry up to N times, then fall back to a Named Tunnel
}

Prevention

Prefer Named Tunnels for anything beyond ad-hoc testing.
Avoid TLS-intercepting proxies on hosts that provision Quick Tunnels.
Check the Cloudflare status page when provisioning fails repeatedly.

When it happens

Trigger: Cloudflare API returns 200 with success:false and empty errors array during `cloudflared tunnel --url ...` quick tunnel setup; intermediaries corrupting the response; Cloudflare-side outage.

Common situations: Corporate proxies/firewalls mangling API responses; Cloudflare status incidents; rate limiting responses lacking error detail.

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

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