gofiber/fiber · error

Servers cannot be empty

Error message

Servers cannot be empty

What it means

The proxy middleware configDefault() requires either a non-empty Servers list or a custom Client (a *fasthttp.LBClient). If both are unset the middleware has no upstream to forward to, so it panics with "Servers cannot be empty". This is a fail-fast guard ensuring the proxy cannot start without a target.

Source

Thrown at middleware/proxy/config.go:131

	if len(config) < 1 {
		return ConfigDefault
	}

	// Override default config
	cfg := config[0]

	// Set default values
	if cfg.Timeout <= 0 {
		cfg.Timeout = ConfigDefault.Timeout
	}

	if cfg.MaxConnsPerHost <= 0 {
		cfg.MaxConnsPerHost = ConfigDefault.MaxConnsPerHost
	}

	// Set default values
	if len(cfg.Servers) == 0 && cfg.Client == nil {
		panic("Servers cannot be empty")
	}
	return cfg
}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Populate Config.Servers with at least one entry like "https://upstream.example.com".
2. If you use a custom load-balancing client, set Config.Client to a non-nil *fasthttp.LBClient instead.
3. Validate that the env/config source for Servers is non-empty before constructing the middleware.

Example fix

// before
app.Use(proxy.New())
// after
app.Use(proxy.New(proxy.Config{
    Servers: []string{"https://upstream.example.com"},
}))

if len(cfg.Servers) == 0 && cfg.Client == nil {
    log.Fatal("proxy: must provide Config.Servers or Config.Client")
}

When it happens

Trigger: Calling proxy.New() with a Config where Servers is nil/empty and Client is nil. This also happens when passing no config at all but intending to use Servers, or when Servers is populated from an env var that resolved to empty.

Common situations: Reading upstream URLs from an environment variable that is unset in the current environment. Passing a config struct built elsewhere that conditionally sets Servers. Forgetting that providing a Client disables the Servers path entirely.

Related errors

• proxy: WithClient requires a non-nil *fasthttp.Client
• Servers cannot be empty
• client: invalid proxy URL: %w
• favicon: file size exceeds max bytes %d
• route handler 'fn' cannot be nil

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/663993ee9adaf706.json. Report an issue: GitHub.