cloudflare/cloudflared · error

Create Tunnel API call failed

Error message

Create Tunnel API call failed

What it means

The Cloudflare Tunnel API call to create the tunnel (client.CreateTunnel) returned an error. cloudflared wraps it with this message; the underlying error typically carries the Cloudflare API error details (auth, quota, name conflict).

Source

Thrown at cmd/cloudflared/tunnel/subcommand_context.go:151

	if secret == "" {
		tunnelSecret, err = generateTunnelSecret()
		if err != nil {
			return nil, errors.Wrap(err, "couldn't generate the secret for your new tunnel")
		}
	} else {
		decodedSecret, err := base64.StdEncoding.DecodeString(secret)
		if err != nil {
			return nil, errors.Wrap(err, "Couldn't decode tunnel secret from base64")
		}
		tunnelSecret = decodedSecret
		if len(tunnelSecret) < 32 {
			return nil, errors.New("Decoded tunnel secret must be at least 32 bytes long")
		}
	}

	tunnel, err := client.CreateTunnel(name, tunnelSecret)
	if err != nil {
		return nil, errors.Wrap(err, "Create Tunnel API call failed")
	}

	credential, err := sc.credential()
	if err != nil {
		return nil, err
	}

	tunnelCredentials := connection.Credentials{
		AccountTag:   credential.AccountID(),
		TunnelSecret: tunnelSecret,
		TunnelID:     tunnel.ID,
		Endpoint:     credential.Endpoint(),
	}
	usedCertPath := false
	if credentialsFilePath == "" {
		originCertDir := filepath.Dir(credential.CertPath())
		credentialsFilePath, err = tunnelFilePath(tunnelCredentials.TunnelID, originCertDir)
		if err != nil {

View on GitHub (pinned to 2253eeeb25)

Solutions

  1. Read the wrapped API error — for a duplicate name, list with `cloudflared tunnel list` and reuse or delete the existing tunnel
  2. Re-run `cloudflared tunnel login` if the cert is expired or for the wrong account
  3. Check Cloudflare API status and retry on transient 5xx
  4. Verify your account/user has tunnel-creation permissions

Example fix

// before
cloudflared tunnel create mytunnel   # already exists
// after
cloudflared tunnel list
cloudflared tunnel delete mytunnel   # or pick a new name
cloudflared tunnel create mytunnel-2
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check for name conflicts
existing, _ := client.ListTunnels()
for _, t := range existing {
    if t.Name == name {
        return fmt.Errorf("tunnel %q already exists", name)
    }
}

Try / catch

if _, err := client.CreateTunnel(name, secret); err != nil {
    var apiErr *cfapi.APIError
    if errors.As(err, &apiErr) && apiErr.StatusCode == 409 {
        // handle duplicate tunnel name
    }
    return fmt.Errorf("Create Tunnel API call failed: %w", err)
}

Prevention

When it happens

Trigger: client.CreateTunnel(name, tunnelSecret) fails during `cloudflared tunnel create`, e.g. 4xx/5xx from the Cloudflare API.

Common situations: A tunnel with the same name already exists in the account (HTTP 1001/duplicate name); expired or wrong-account origin cert; lacking permission to create tunnels; API outages or rate limits.

Related errors

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