gofiber/fiber · error

use: invalid handler %v

Error message

use: invalid handler %v

What it means

Panics from domain.go:367 inside domainRouter.Use when an argument is not a string (prefix), []string (prefixes), *App (sub-app to mount), or a value convertible to a fiber.Handler. Use on a domain-scoped router accepts the same polymorphic arg list as app.Use; anything else is a programmer error.

Source

Thrown at domain.go:367

//	})
func (d *domainRouter) 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 []string:
			prefixes = arg
		case *App:
			subApp = arg
		default:
			handler, ok := toFiberHandler(arg)
			if !ok {
				panic(fmt.Sprintf("use: invalid handler %v", reflect.TypeOf(arg)))
			}
			handlers = append(handlers, handler)
		}
	}

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

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

		wrapped := d.wrapHandlers(handlers)
		d.app.register([]string{methodUse}, d.registerPath(prefix), d.registerGroup(), wrapped...)
	}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Pass only fiber.Handler (func(c fiber.Ctx) error) or compatible functions, plus optional string/[]string prefixes or *App.
2. Wrap non-conforming functions: convert func() {} into func(c fiber.Ctx) error { ...; return nil }.
3. Double-check argument order - prefix strings must precede handlers.

Example fix

// before
api := app.Domain("api.example.com")
api.Use(func() { log.Println("hi") }) // wrong signature

// after
api := app.Domain("api.example.com")
api.Use(func(c fiber.Ctx) error {
    log.Println("hi")
    return c.Next()
})

// fiber exposes toFiberHandler internally; replicate the accepted shapes:
func isValidUseArg(v any) bool {
    switch v.(type) {
    case string, []string, *fiber.App:
        return true
    }
    // accept any func(fiber.Ctx) error
    if reflect.TypeOf(v).Kind() == reflect.Func {
        return true
    }
    return false
}

When it happens

Trigger: app.Domain("api.example.com").Use(123), .Use(someStruct{}), .Use(nil) of an unsupported type, or passing an int/float/bool argument. Also when a handler variable of the wrong function shape (e.g. func() with no Ctx arg) is passed and toFiberHandler returns ok=false.

Common situations: Passing a plain function with the wrong signature; passing a struct thinking it is a handler; copy-paste from a non-fiber framework; nil interface of unhandled type.

Related errors

• route handler 'fn' cannot be nil
• Domain pattern cannot be empty
• Domain pattern '%s' exceeds RFC 1035 maximum of 253 characte
• Domain pattern '%s' has %d parts, which exceeds the maximum
• Domain pattern '%s' contains empty label at position %d

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