cloudflare/cloudflared · error

failed to parse quick Tunnel ID

Error message

failed to parse quick Tunnel ID

What it means

Raised in RunQuickTunnel after a successful provisioning response: the JSON was decoded but the returned quick-tunnel ID could not be parsed into a UUID, so the free-tunnel credentials are unusable and the quick tunnel run aborts. Indicates an unexpected/invalid response body from the quick-tunnel service.

Source

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

	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
	}

	cliutil.LogTable(sc.log, []string{
		"Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):",
		url,
	})

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Verify you are using the official default quick-service endpoint (remove custom quick-service overrides)
2. Retry provisioning — a malformed one-off response may be transient
3. Upgrade cloudflared to the latest release
4. Check network middleboxes that could alter response bodies

if _, err := uuid.Parse(data.Result.ID); err != nil {
    return fmt.Errorf("quick-tunnel returned invalid tunnel ID %q", data.Result.ID)
}

func isValidUUID(s string) bool {
    _, err := uuid.Parse(s)
    return err == nil
}

When it happens

Trigger: uuid.Parse(data.Result.ID) fails after a 2xx response with data.Success == true from the quick-tunnel service.

Common situations: A non-Cloudflare/custom quick-service returning success with an arbitrary ID; an API change or truncated response; middlebox tampering with the JSON body.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• ErrUnauthorized
• ErrBadRequest
• unable to generate a connector UUID: %w
• failed to unmarshal quick Tunnel
• couldn't create client to talk to Cloudflare Tunnel backend

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