labstack/echo · critical

echo basic-auth middleware requires a validator function

Error message

echo basic-auth middleware requires a validator function

What it means

Returned by BasicAuthConfig.ToMiddleware when config.Validator is nil, then converted to a panic by toMiddlewareOrPanic since BasicAuthWithConfig cannot return an error. BasicAuth requires a Validator function to check credentials; without one the middleware cannot authenticate. This is a startup/configuration error, not a runtime request error.

Source

Thrown at middleware/basic_auth.go:99

)

// BasicAuth returns an BasicAuth middleware.
//
// For valid credentials it calls the next handler.
// For missing or invalid credentials, it sends "401 - Unauthorized" response.
func BasicAuth(fn BasicAuthValidator) echo.MiddlewareFunc {
	return BasicAuthWithConfig(BasicAuthConfig{Validator: fn})
}

// BasicAuthWithConfig returns an BasicAuthWithConfig middleware with config.
func BasicAuthWithConfig(config BasicAuthConfig) echo.MiddlewareFunc {
	return toMiddlewareOrPanic(config)
}

// ToMiddleware converts BasicAuthConfig to middleware or returns an error for invalid configuration
func (config BasicAuthConfig) ToMiddleware() (echo.MiddlewareFunc, error) {
	if config.Validator == nil {
		return nil, errors.New("echo basic-auth middleware requires a validator function")
	}
	if config.Skipper == nil {
		config.Skipper = DefaultSkipper
	}
	realm := defaultRealm
	if config.Realm != "" {
		realm = config.Realm
	}
	realm = strconv.Quote(realm)
	limit := cmp.Or(config.AllowedCheckLimit, 1)

	return func(next echo.HandlerFunc) echo.HandlerFunc {
		return func(c *echo.Context) error {
			if config.Skipper(c) {
				return next(c)
			}

			var lastError error

View on GitHub (pinned to 05489dc173)

Solutions

1. Provide a Validator function: middleware.BasicAuth(func(c echo.Context, user, pass string) (bool, error) { ... })
2. If using BasicAuthWithConfig, set config.Validator to a BasicAuthValidator function
3. Use config.ToMiddleware() (which returns an error) instead of BasicAuthWithConfig if you want to handle the error without panicking

Example fix

// before
mw := middleware.BasicAuthWithConfig(middleware.BasicAuthConfig{}) // panic

// after
mw := middleware.BasicAuth(func(c echo.Context, u, p string) (bool, error) {
    return u == "admin" && p == "secret", nil
})

// Use ToMiddleware (returns error) instead of WithConfig (panics)
if _, err := (middleware.BasicAuthConfig{}).ToMiddleware(); err != nil {
    log.Fatal("BasicAuth requires Validator:", err)
}

// Since BasicAuthWithConfig panics, use a recover or ToMiddleware
defer func() {
    if r := recover(); r != nil {
        log.Fatal("middleware setup failed:", r)
    }
}()
mw := middleware.BasicAuthWithConfig(cfg)

When it happens

Trigger: Calling middleware.BasicAuthWithConfig(middleware.BasicAuthConfig{}) without setting Validator, or calling middleware.BasicAuth(nil). The panic occurs at server setup time when the middleware chain is built.

Common situations: Copy-pasting a BasicAuth example but deleting the Validator assignment. Refactoring that accidentally removes the Validator. Conditional config where a branch leaves Validator nil.

Related errors

• echo body-dump middleware requires a handler function
• invalid gzip level
• panic: err from config.ToMiddleware() in RequestLoggerWithCo
• timeout must be set
• at least one AllowOrigins is required or UnsafeAllowOriginFu

AI-assisted analysis of labstack/echo@05489dc173 (2026-08-04). Data as JSON: /data/errors/e8a87174f784d1d4.json. Report an issue: GitHub.