gofiber/fiber · error

use: invalid handler

Error message

use: invalid handler %v

What it means

Group.Use accepts the same argument shapes as App.Use: string prefix, []string prefixes, *App sub-app, and handlers convertible via toFiberHandler (Fiber, Express-style, net/http, fasthttp signatures). Anything else — including nil and unsupported func signatures — falls through to the default branch and panics, printing reflect.TypeOf(arg). The message differs from the domain variant only by a trailing '\n'.

Solutions

1. Convert the argument to a supported signature, preferably fiber.Handler (func(Ctx) error).
2. For net/http handlers, pass the value directly only when its static type is exactly http.HandlerFunc/http.Handler/func(http.ResponseWriter,*http.Request); otherwise adapt it.
3. Eliminate typed-nil middleware values; pass a real handler or omit the argument.

Example fix

// before
grp.Use("/x", myStruct{})
grp.Use("/x", func(c *fiber.Ctx) error { return nil }) // v2-style
// after
grp.Use("/x", func(c fiber.Ctx) error { return nil })

// same shape as error 264; reuse isUseArg for Group.Use arguments.
for _, a := range args {
    if !isUseArg(a) {
        return fmt.Errorf("unsupported Group.Use arg %T", a)
    }
}

defer func() {
    if r := recover(); r != nil {
        log.Fatalf("Group.Use arg rejected: %v", r)
    }
}()
grp.Use(args...)

When it happens

Trigger: Calling grp.Use(...) with an argument whose dynamic type matches none of the switch cases — e.g. an int, a struct, a chan, a typed-nil handler, or a func with an unsupported signature (wrong arity, wrong return type, pointer-to-interface receiver).

Common situations: Passing a typed-nil middleware (var mw MyMw = nil); a handler with signature drift after a fiber major-version upgrade (e.g. v2 func(*fiber.Ctx) into v3 which uses the Ctx interface); leaving a debug placeholder integer/zero-struct in the middleware chain; wrapping a handler in a custom type that hides the underlying func signature.

Related errors

• : invalid handler # (%T)
• use: invalid handler
• route handler 'fn' cannot be nil
• use: invalid handler
• Domain pattern cannot be empty

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

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