coredns/coredns · error · plugin.Error

more than %d TOs configured: %d

Error message

more than %d TOs configured: %d

What it means

The forward plugin caps the number of upstream (TO) addresses per forward stanza at max (len of f.toEntries). During setup, if a stanza lists more TO addresses than allowed, setup returns this error and CoreDNS fails to load the plugin. It is a hard configuration limit, not a runtime condition.

Source

Thrown at plugin/forward/setup.go:38

	pkgtls "github.com/coredns/coredns/plugin/pkg/tls"
	"github.com/coredns/coredns/plugin/pkg/transport"

	"github.com/miekg/dns"
)

func init() {
	plugin.Register("forward", setup)
}

func setup(c *caddy.Controller) error {
	fs, err := parseForward(c)
	if err != nil {
		return plugin.Error("forward", err)
	}
	for i := range fs {
		f := fs[i]
		if len(f.toEntries) > max {
			return plugin.Error("forward", fmt.Errorf("more than %d TOs configured: %d", max, len(f.toEntries)))
		}

		if i == len(fs)-1 {
			// last forward: point next to next plugin
			dnsserver.GetConfig(c).AddPlugin(func(next plugin.Handler) plugin.Handler {
				f.Next = next
				return f
			})
		} else {
			// middle forward: point next to next forward
			nextForward := fs[i+1]
			dnsserver.GetConfig(c).AddPlugin(func(plugin.Handler) plugin.Handler {
				f.Next = nextForward
				return f
			})
		}

		c.OnStartup(func() error {

View on GitHub (pinned to 558c9757a9)

Solutions

1. Reduce the number of TO addresses in the forward stanza to at most the allowed maximum.
2. Split upstreams across multiple forward stanzas with different zones (policy is per-stanza anyway).
3. Place a local load balancer (or dnsmasq/service VIP) in front of many upstreams and forward to that single address.

Example fix

// before
forward . 8.8.8.8 8.8.4.4 1.1.1.1 1.0.0.1 9.9.9.9 149.112.112.112 208.67.222.222 208.67.220.220
// after (one stanza per zone or trimmed list)
forward . 8.8.8.8 1.1.1.1 9.9.9.9

if len(toAddresses) > maxAllowedTOs {
    return fmt.Errorf("too many upstreams: %d", len(toAddresses))
}

When it happens

Trigger: A Corefile forward stanza (or one produced by parseForward) listing more than max upstream addresses, e.g. 'forward . 1.1.1.1 8.8.8.8 ...' exceeding the cap; exercised in TestMultiForward/TestSetTapPlugin.

Common situations: Copy-pasting a long list of public resolvers into one forward stanza; generated configs enumerating many upstreams; older deployments migrated to a version with a stricter cap.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• unable to normalize '%s'
• no valid upstream addresses found
• no forwarder defined
• this plugin can only be used once per Server Block
• max_age (%s) must not be less than expire (%s)

AI-assisted analysis of coredns/coredns@558c9757a9 (2026-09-06). Data as JSON: /api/errors/b8db0bc1da83fd7e. Report an issue: GitHub.