gofiber/fiber · error

Servers cannot be empty

Error message

Servers cannot be empty

What it means

proxy.Balancer requires at least one upstream. configDefault panics when Config.Servers is empty AND Config.Client is nil — a balancer with no backends cannot forward any request, so this is treated as a hard configuration error rather than a runtime failure on the first request. Note that supplying Config.Client bypasses the Servers requirement (and the Server-validating loop in proxy.go).

Solutions

1. Provide a non-empty Servers list: proxy.Balancer(proxy.Config{Servers: []string{"http://localhost:8081", "http://localhost:8082"}}).
2. Provide a pre-built Client (*fasthttp.LBClient) if you need full control over the upstream set.
3. Guard the app.Use(proxy.Balancer(...)) call so the middleware is only registered when upstreams are configured.

Example fix

// before
app.Use(proxy.Balancer(proxy.Config{}))

// after
app.Use(proxy.Balancer(proxy.Config{
    Servers: []string{"http://localhost:8081"},
}))

func buildProxyConfig(servers []string, client *fasthttp.LBClient) (proxy.Config, error) {
    if len(servers) == 0 && client == nil {
        return proxy.Config{}, errors.New("proxy: Servers cannot be empty (or set Client)")
    }
    return proxy.Config{Servers: servers, Client: client}, nil
}

func hasProxyTarget(servers []string, client *fasthttp.LBClient) bool {
    return len(servers) > 0 || client != nil
}

When it happens

Trigger: proxy.Balancer() with no args, or proxy.Balancer(proxy.Config{}) where neither Servers nor Client is set. Also reached when Servers is built from an env var that is empty and the code still calls Balancer.

Common situations: Backend list loaded from config that is empty in a local/dev environment; refactor that moves Servers into a Client but leaves the old Balancer(config) call with an empty Servers; conditional wiring that drops the config argument.

Related errors

• ErrUpstreamSchemeNotAllowed
• fiber: keyauth middleware requires a validator function
• hostauthorization: AllowedHosts or AllowedHostsFunc is…
• proxy: invalid dial address
• proxy: parse upstream

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/663993ee9adaf706. Report an issue: GitHub.

Appendix: 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 a105acad6c)