cloudflare/cloudflared · error

v.Error

Error message

v.Error

What it means

cloudflared's auto-updater calls a Workers service that returns a VersionResponse JSON; if the server includes a non-empty `error` field, the client surfaces it verbatim as this error (the field's value is the message). It means the update-check service itself rejected or failed the request server-side.

Source

Thrown at cmd/cloudflared/updater/workers_service.go:93

	req.URL.RawQuery = q.Encode()
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != 200 {
		return nil, fmt.Errorf("unable to check for update: %d", resp.StatusCode)
	}

	var v VersionResponse
	if err := json.NewDecoder(resp.Body).Decode(&v); err != nil {
		return nil, err
	}

	if v.Error != "" {
		return nil, errors.New(v.Error)
	}

	versionToUpdate := ""
	if v.ShouldUpdate {
		versionToUpdate = v.Version
	}

	return NewWorkersVersion(v.URL, versionToUpdate, v.Checksum, s.targetPath, v.UserMessage, v.IsCompressed), nil
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Retry later; this is typically a server-side condition
2. Check your proxy/firewall is not intercepting the update endpoint's JSON
3. Upgrade cloudflared manually (download the release binary) if the running version is old
4. Disable automatic updates if unattended (e.g. --no-autoupdate or TUNNEL_NO_AUTOUPDATE)

// tolerate transient update-service errors
if err := updater.Check(ctx); err != nil {
    log.Warn().Err(err).Msg("update check failed; continuing with current version")
    // schedule a retry with backoff; do not fail the tunnel
}

When it happens

Trigger: The Workers update service responds with JSON like {"error":"..."} — e.g. during service incidents, malformed client request metadata, or unsupported client versions.

Common situations: Cloudflare-side update service outages; proxy/firewall rewriting the response; running a very old cloudflared whose request no longer satisfies the service contract.

Related errors

• failed to create tunnel
• Expected to find a single tunnel with uuid %v but found %d t
• failed to get checksums: {0}
• failed to upload checksum: {0}
• ErrUnauthorized

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