cloudflare/cloudflared · error

Failed to %s: %s

Error message

Failed to %s: %s

What it means

API-error formatting in RESTClient.statusCodeToError: the response was JSON and contained structured error entries, so the client builds a 'Failed to <op>: <combined reasons>' error instead of falling through to status-code sentinel errors (ErrBadRequest, ErrUnauthorized, etc.). It carries the Cloudflare API's own explanation of why the operation was rejected.

Source

Thrown at cfapi/base_client.go:226

	}
	return fmt.Errorf("API errors: %s", messagesBuilder.String())
}

type apiError struct {
	Code    json.Number `json:"code,omitempty"`
	Message string      `json:"message,omitempty"`
}

func (e apiError) Error() string {
	return fmt.Sprintf("code: %v, reason: %s", e.Code, e.Message)
}

func (r *RESTClient) statusCodeToError(op string, resp *http.Response) error {
	if resp.Header.Get("Content-Type") == "application/json" {
		var errorsResp response
		if json.NewDecoder(resp.Body).Decode(&errorsResp) == nil {
			if err := errorsResp.checkErrors(); err != nil {
				return errors.Errorf("Failed to %s: %s", op, err)
			}
		}
	}

	switch resp.StatusCode {
	case http.StatusOK:
		return nil
	case http.StatusBadRequest:
		return ErrBadRequest
	case http.StatusUnauthorized, http.StatusForbidden:
		return ErrUnauthorized
	case http.StatusNotFound:
		return ErrNotFound
	}
	return errors.Errorf("API call to %s failed with status %d: %s", op,
		resp.StatusCode, http.StatusText(resp.StatusCode))
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Read the embedded reasons from the API error payload — they state the exact rejection cause.
2. Fix the request (bad route CIDR, duplicate name, missing permission) per the API message.
3. For authorization failures, re-login (`cloudflared tunnel login`) to refresh cert.pem.

When it happens

Trigger: Thrown at cfapi/base_client.go:226 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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