gofiber/fiber · error

use: invalid handler %v

Error message

use: invalid handler %v

What it means

Group.Use accepts variadic arguments that may be a prefix string, a *App (for mounting), a []string (multiple prefixes), or a handler convertible via toFiberHandler (Fiber handlers, Express-style handlers, net/http handlers, fasthttp handlers). Any argument of an unsupported type panics with "use: invalid handler" and the Go type name.

Source

Thrown at group.go:87

// This method will match all HTTP verbs: GET, POST, PUT, HEAD etc...
func (grp *Group) Use(args ...any) Router {
	var subApp *App
	var prefix string
	var prefixes []string
	var handlers []Handler

	for i := range args {
		switch arg := args[i].(type) {
		case string:
			prefix = arg
		case *App:
			subApp = arg
		case []string:
			prefixes = arg
		default:
			handler, ok := toFiberHandler(arg)
			if !ok {
				panic(fmt.Sprintf("use: invalid handler %v\n", reflect.TypeOf(arg)))
			}
			handlers = append(handlers, handler)
		}
	}

	if len(prefixes) == 0 {
		prefixes = append(prefixes, prefix)
	}

	for _, prefix := range prefixes {
		if subApp != nil {
			return grp.mount(prefix, subApp)
		}

		grp.app.register([]string{methodUse}, getGroupPath(grp.Prefix, prefix), grp, handlers...)
	}

	if !grp.hasAnyRoute {

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Pass only values of types toFiberHandler accepts: fiber.Handler, func(Ctx), the Express-style func(Req,Res,...) signatures, http.HandlerFunc/http.Handler, or fasthttp handler types.
2. Wrap custom middleware in an adapter returning fiber.Handler before passing to Use.
3. Check the reported Go type in the panic message to find the offending argument.

Example fix

// before
grp.Use(myPlainStruct{})
// after
grp.Use(func(c fiber.Ctx) error {
    // adapt myPlainStruct behavior here
    return c.Next()
})

switch arg.(type) {
case string, *App, []string:
    // ok
case fiber.Handler, func(fiber.Ctx),
    func(Req, Res) error, func(Req, Res),
    func(Req, Res, func() error) error, func(Req, Res, func() error),
    func(Req, Res, func(error)), func(Req, Res, func(error)) error,
    func(Req, Res, func(error) error), func(Req, Res, func(error) error) error,
    http.HandlerFunc, http.Handler, func(http.ResponseWriter, *http.Request),
    fasthttp.RequestHandler, func(*fasthttp.RequestCtx) error:
    // ok
default:
    log.Fatalf("use: unsupported handler type %T", arg)
}

func isUsableHandler(arg any) bool {
    switch arg.(type) {
    case string, *App, []string:
        return true
    default:
        _, ok := toFiberHandlerPublic(arg) // mirror of internal adapter
        return ok
    }
}

When it happens

Trigger: Passing a plain struct, an int, a string pointer, or any function signature not in the supported list to Group.Use(). Also triggered by passing a typed nil that isn't one of the recognized handler types.

Common situations: Passing an http.HandlerFunc where a fiber.Handler was expected is actually fine, but passing a custom middleware struct that doesn't implement a recognized signature fails. Wrapping a non-Fiber library middleware. Typos like passing a method value with the wrong signature.

Related errors

• use: invalid handler %v
• route handler 'fn' cannot be nil
• %v
• %s: invalid handler #%d (%T)\n
• use: invalid handler %v\n

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