gofr-dev/gofr · error

burst must be positive

Error message

burst must be positive

What it means

errInvalidBurst is returned by RateLimiterConfig.Validate when Burst is zero or negative. The burst size caps how many requests can pass at once via the token bucket; a non-positive burst makes the limiter useless, so it is rejected.

Source

Thrown at pkg/gofr/http/middleware/rate_limiter.go:20

import (
	"context"
	"errors"
	"fmt"
	"math"
	"net"
	"net/http"
	"strings"

	gofrHttp "gofr.dev/pkg/gofr/http"
)

var (
	// errInvalidRequestsPerSecond is returned when RequestsPerSecond is not positive.
	errInvalidRequestsPerSecond = errors.New("requestsPerSecond must be positive")

	// errInvalidBurst is returned when Burst is not positive.
	errInvalidBurst = errors.New("burst must be positive")
)

// RateLimiterConfig holds configuration for rate limiting.
//
// Note: The default implementation uses in-memory token buckets and is suitable
// for single-pod deployments. In multi-pod deployments, each pod will enforce
// limits independently. For distributed rate limiting across multiple pods,
// a Redis-backed store can be implemented in a future update.
//
// Security: When using PerIP=true, only enable TrustedProxies if your application
// is behind a trusted reverse proxy (nginx, ALB, etc.) that sets X-Forwarded-For.
// Without trusted proxies, clients can spoof IP addresses to bypass rate limits.
//
// Cleanup: The rate limiter starts a background goroutine that runs for the
// application lifetime. This is acceptable for long-running servers but consider
// calling Store.StopCleanup() in shutdown handlers if needed.
type RateLimiterConfig struct {
	RequestsPerSecond float64

View on GitHub (pinned to 187eb24962)

Solutions

1. Set Burst to a positive integer (commonly a multiple of RequestsPerSecond, e.g. 2x)
2. Validate all rate limiter fields in your config-loading layer before constructing the middleware
3. Use the Validate() method proactively on user-supplied configs and surface a clear message

Example fix

// before
middleware.RateLimiterConfig{RequestsPerSecond: 10}
// after
middleware.RateLimiterConfig{RequestsPerSecond: 10, Burst: 20}

if cfg.Burst <= 0 { return fmt.Errorf("Burst must be > 0, got %v", cfg.Burst) }

func validRateConfig(c RateLimiterConfig) bool { return c.RequestsPerSecond > 0 && c.Burst > 0 }

When it happens

Trigger: Constructing a RateLimiterConfig without setting Burst, or explicitly setting Burst to 0/negative while RequestsPerSecond is valid.

Common situations: Setting only RequestsPerSecond and assuming Burst is optional; deriving Burst from a config value that defaults to 0; misunderstanding that Burst must also be positive.

Related errors

• requestsPerSecond must be positive
• invalid rate limiter config: %v
• %w: deleting document: %w
• invalid Azure configuration: share name is required
• invalid Azure configuration: account name is required

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/6b966230faab7b2b. Report an issue: GitHub.