What causes "error while creating backend client" in cloudflare/cloudflared?

Run `cloudflared tunnel login` to generate a valid origin cert, or pass --origincert pointing at an existing cert.pem

error while creating backend client

Error message

error while creating backend client

What it means

`listRoutes` wraps the error returned by `subcommandContext.client()` when constructing the Cloudflare API (Tunnel Store) client fails, using the shared noClientMsg text. Client construction fails when the origin certificate cannot be read or parsed, or the API URL is invalid — so no route listing can proceed.

Source

Thrown at cmd/cloudflared/tunnel/subcommand_context_teamnet.go:17

package tunnel

import (
	"net"

	"github.com/google/uuid"
	"github.com/pkg/errors"

	"github.com/cloudflare/cloudflared/cfapi"
)

const noClientMsg = "error while creating backend client"

func (sc *subcommandContext) listRoutes(filter *cfapi.IpRouteFilter) ([]*cfapi.DetailedRoute, error) {
	client, err := sc.client()
	if err != nil {
		return nil, errors.Wrap(err, noClientMsg)
	}
	return client.ListRoutes(filter)
}

func (sc *subcommandContext) addRoute(newRoute cfapi.NewRoute) (cfapi.Route, error) {
	client, err := sc.client()
	if err != nil {
		return cfapi.Route{}, errors.Wrap(err, noClientMsg)
	}
	return client.AddRoute(newRoute)
}

func (sc *subcommandContext) deleteRoute(id uuid.UUID) error {
	client, err := sc.client()
	if err != nil {
		return errors.Wrap(err, noClientMsg)
	}
	return client.DeleteRoute(id)

View on GitHub (pinned to 2253eeeb25)

Solutions

Run `cloudflared tunnel login` to generate a valid origin cert, or pass --origincert pointing at an existing cert.pem
Verify the cert file exists and is readable at the configured path (default ~/.cloudflared/cert.pem)
Check --api-url points to a valid Cloudflare API endpoint
Confirm the command runs as a user with access to the cert file

Example fix

// before (no guard — error surfaces late)
client, err := sc.client()
if err != nil {
    return nil, errors.Wrap(err, noClientMsg)
}
// after (check credentials before invoking the command)
if _, err := os.Stat(origincertPath); err != nil {
    return nil, fmt.Errorf("origin cert not found at %s; run `cloudflared tunnel login` first", origincertPath)
}

Defensive patterns

Strategy: validation

Validate before calling

certPath := "/root/.cloudflared/cert.pem"
if info, err := os.Stat(certPath); err != nil || info.IsDir() {
    return errors.New("origin cert missing; run `cloudflared tunnel login`")
}

Try / catch

routes, err := listRoutes(filter)
if err != nil && strings.Contains(err.Error(), "error while creating backend client") {
    // credentials problem — re-login or fix --origincert before retrying
}

Prevention

Run `cloudflared tunnel login` before any tunnel/route/vnet command
Pass an explicit --origincert in scripts and CI instead of relying on $HOME
Mount and chmod 600 the cert.pem in containers
Never point --origincert at a tunnel credentials JSON; it must be cert.pem

When it happens

Trigger: Running `cloudflared tunnel route ip list` (or any teamnet route command) where credentials.Read fails (missing/invalid ~/.cloudflared/cert.pem or --origincert path) or cred.Client() cannot build the client (bad --api-url, malformed cert).

Common situations: Running route commands on a CI box without having run `cloudflared tunnel login`; pointing --origincert at a tunnel credentials JSON instead of the origin cert; corrupt cert.pem; FIPS/fedramp endpoint misconfiguration.

Related errors

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