cockroachdb/cockroach · critical

invalid trusted proxy CIDRs

Error message

invalid trusted proxy CIDRs

What it means

The roachprod-centralized API server configures gin at startup and calls SetTrustedProxies with the configured CIDR list; invalid CIDRs make gin return an error, which is wrapped with 'invalid trusted proxy CIDRs' and panicked. Failing fast is intentional: silently ignoring the config would let X-Forwarded-For spoofing bypass service-account IP origin checks.

Source

Thrown at pkg/cmd/roachprod-centralized/app/api.go:77

func (a *Api) Init(l *logger.Logger) {

	// Init gin engine and set up server-wide middlewares
	gin.DefaultWriter = l
	if l.LogLevel >= slog.LevelInfo {
		gin.SetMode(gin.ReleaseMode)
	} else {
		gin.SetMode(gin.DebugMode)
	}

	// Full API mode: create gin engine with all middlewares
	ginEngine := gin.New()

	// Configure trusted proxies for correct ClientIP() resolution.
	// Without this, Gin trusts all proxies by default, allowing X-Forwarded-For
	// spoofing which bypasses service account IP origin checks.
	if err := ginEngine.SetTrustedProxies(a.trustedProxies); err != nil {
		l.Error("invalid trusted proxy configuration", slog.Any("error", err))
		panic(errors.Wrap(err, "invalid trusted proxy CIDRs"))
	}
	if len(a.trustedProxies) == 0 {
		l.Warn("no trusted proxies configured; ClientIP() will use RemoteAddr directly")
	} else {
		l.Info("trusted proxies configured", slog.Any("cidrs", a.trustedProxies))
	}
	ginEngine.Use(gin.Recovery())
	ginEngine.Use(a.securityHeaders())
	ginEngine.Use(a.requestSizeLimit())
	ginEngine.Use(a.requestID())
	ginEngine.Use(a.traceContext())
	ginEngine.Use(a.slogFormatter(l))

	// Add Prometheus metrics endpoint
	if a.metrics {
		m := ginmetrics.GetMonitor()
		m.SetMetricPrefix(fmt.Sprintf("%s_", configtypes.MetricsNamespace))
		m.SetMetricPath("/metrics")

View on GitHub (pinned to 8812064a01)

Solutions

1. Validate every entry with net.ParseCIDR before starting the server
2. Pass a properly quoted comma list of CIDRs: --trusted-proxies='10.0.0.0/8,127.0.0.1/32'
3. Use 0.0.0.0/0 only if every hop is trusted; omit the flag to trust none (ClientIP falls back to RemoteAddr, which the server logs a warning about)

Example fix

# before
--trusted-proxies=10.0.0.1,my-lb.example.com

# after
--trusted-proxies='10.0.0.0/8,127.0.0.1/32'

When it happens

Trigger: Passing malformed proxy entries in the config/flag: 'not-a-cidr', '10.0.0.1/8/9', a bare hostname where a CIDR is required, stray spaces, or an empty element produced by a trailing comma.

Common situations: First deployment behind a load balancer: operators copy the LB hostname instead of its CIDR, paste a comma list without quoting so the shell mangles it, or leave an empty final element after editing.

Related errors

• Error response from server: ${resp.status}
• error while processing file %s
• failed parsing datum string as
• cannot set both COCKROACH_FORCE_DEV_VERSION and COCKROACH_TE
• cannot have two files with the same basename in DISTDIR_FILE

AI-assisted analysis of cockroachdb/cockroach@8812064a01 (2026-08-15). Data as JSON: /api/errors/ca2eae6ccbd32d42. Report an issue: GitHub.