echo body-dump middleware requires a handler function

Error message

echo body-dump middleware requires a handler function

What it means

Returned by BodyDumpConfig.ToMiddleware when config.Handler is nil, then converted to a panic by toMiddlewareOrPanic. BodyDump middleware captures request and response payloads and must have a callback (BodyDumpHandler) to deliver them to; without a Handler there is nothing to do with the captured data. This is a startup/configuration error.

Source

Thrown at middleware/body_dump.go:75

// in production), explicitly set MaxRequestBytes and MaxResponseBytes to -1.
func BodyDump(handler BodyDumpHandler) echo.MiddlewareFunc {
	return BodyDumpWithConfig(BodyDumpConfig{Handler: handler})
}

// BodyDumpWithConfig returns a BodyDump middleware with config.
// See: `BodyDump()`.
//
// SECURITY: If MaxRequestBytes and MaxResponseBytes are not set (zero values), they default
// to 5MB each to prevent DoS attacks via large payloads. Set them explicitly to -1 to disable
// limits if needed for your use case.
func BodyDumpWithConfig(config BodyDumpConfig) echo.MiddlewareFunc {
	return toMiddlewareOrPanic(config)
}

// ToMiddleware converts BodyDumpConfig to middleware or returns an error for invalid configuration
func (config BodyDumpConfig) ToMiddleware() (echo.MiddlewareFunc, error) {
	if config.Handler == nil {
		return nil, errors.New("echo body-dump middleware requires a handler function")
	}
	if config.Skipper == nil {
		config.Skipper = DefaultSkipper
	}
	if config.MaxRequestBytes == 0 {
		config.MaxRequestBytes = 5 * MB
	}
	if config.MaxResponseBytes == 0 {
		config.MaxResponseBytes = 5 * MB
	}

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

			reqBuf := bodyDumpBufferPool.Get().(*bytes.Buffer)

View on GitHub (pinned to 05489dc173)

Solutions

Provide a Handler function: middleware.BodyDump(func(c echo.Context, req, res []byte, err error) { log.Printf(...) })
If using BodyDumpWithConfig, set config.Handler to a BodyDumpHandler function
Use config.ToMiddleware() to get an error instead of a panic if you prefer graceful handling

Example fix

// before
mw := middleware.BodyDumpWithConfig(middleware.BodyDumpConfig{}) // panic

// after
mw := middleware.BodyDump(func(c echo.Context, reqBody, resBody []byte, err error) {
    log.Printf("req=%s res=%s", reqBody, resBody)
})

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

defer func() {
    if r := recover(); r != nil {
        log.Fatal("middleware setup failed:", r)
    }
}()
mw := middleware.BodyDumpWithConfig(cfg)

Prevention

Always pass a Handler callback to BodyDump / BodyDumpConfig
Use config.ToMiddleware() to handle config errors gracefully
Build middleware chains in an init or setup function with tests

When it happens

Trigger: Calling middleware.BodyDumpWithConfig(middleware.BodyDumpConfig{}) without setting Handler, or calling middleware.BodyDump(nil). The panic happens at middleware chain construction time.

Common situations: Enabling BodyDump for logging/debugging but forgetting to wire the callback. Refactoring that removes the Handler assignment. Copy-paste error from docs.

Related errors

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