coredns/coredns · error

num sockets exceeds maximum (%d): %d

Error message

num sockets exceeds maximum (%d): %d

What it means

multisocket caps the number of sockets at maxNumSockets to prevent file-descriptor exhaustion and unbounded resource use. parseNumSockets returns this error when the Corefile argument exceeds that maximum during setup.

Source

Thrown at plugin/multisocket/multisocket.go:50

	if len(args) > 1 || c.Next() {
		return c.ArgErr()
	}

	if len(args) == 0 {
		// Nothing specified; use default that is equal to GOMAXPROCS.
		config.NumSockets = runtime.GOMAXPROCS(0)
		return nil
	}

	numSockets, err := strconv.Atoi(args[0])
	if err != nil {
		return fmt.Errorf("invalid num sockets: %w", err)
	}
	if numSockets < 1 {
		return fmt.Errorf("num sockets can not be zero or negative: %d", numSockets)
	}
	if numSockets > maxNumSockets {
		return fmt.Errorf("num sockets exceeds maximum (%d): %d", maxNumSockets, numSockets)
	}
	config.NumSockets = numSockets

	return nil
}

View on GitHub (pinned to 558c9757a9)

Solutions

1. Lower the value to at or below maxNumSockets (see plugin/multisocket/multisocket.go for the constant)
2. Remove the directive to use the GOMAXPROCS default
3. Rebuild CoreDNS with a larger maxNumSockets constant if you genuinely need more sockets
4. Verify ulimit -n allows the number of sockets you intend to open

Example fix

// before
multisocket 512
// after
multisocket 64

const maxNumSockets = <check plugin source>; n, _ := strconv.Atoi(value); if n > maxNumSockets { n = maxNumSockets }

if err := setup(...); err != nil && strings.Contains(err.Error(), "exceeds maximum") { /* reduce the value or rebuild with a larger cap */ }

When it happens

Trigger: Corefile contains e.g. `multisocket 512` where 512 > maxNumSockets, so setup aborts CoreDNS startup.

Common situations: Over-tuning on machines with many CPUs; copying a config from a host with a higher compiled max; misunderstanding the plugin's 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

• reload duration value is expected
• at least one address or interface name is expected
• at least one address or interface must be given to except su
• invalid serve_stale_policy: %s
• cache type for disable must be %q or %q

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