What causes "fiber: Config.RegexHandler must not return nil" in gofiber/fiber?

Return a real compiled matcher from RegexHandler for every input (regexp.MustCompile never returns nil - it panics on bad patterns instead).

gofiber/fiber · error

fiber: Config.RegexHandler must not return nil

Error message

fiber: Config.RegexHandler must not return nil

What it means

Panics from constraint.go:46 inside compileRegex when RegexHandler returns a nil matcher for a given pattern (isNilRegexMatcher check). Unlike the static validateRegexHandler checks, this only triggers at route registration when a regex(...) constraint is compiled and the handler yields nil - the value check validateRegexHandler cannot perform statically.

Source

Thrown at constraint.go:46

		return true
	}
	matcherValue := reflect.ValueOf(matcher)
	switch matcherValue.Kind() {
	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
		return matcherValue.IsNil()
	default:
		return false
	}
}

func compileRegex(handler any, pattern string) regexMatcher {
	result := reflect.ValueOf(handler).Call([]reflect.Value{reflect.ValueOf(pattern)})
	matcher, ok := result[0].Interface().(regexMatcher)
	if !ok {
		panic("fiber: Config.RegexHandler return type must support MatchString(string) bool")
	}
	if isNilRegexMatcher(matcher) {
		panic("fiber: Config.RegexHandler must not return nil")
	}
	return matcher
}

func validateRegexHandler(handler any) any {
	if handler == nil {
		return regexp.MustCompile
	}
	handlerValue := reflect.ValueOf(handler)
	handlerType := handlerValue.Type()
	if handlerType.Kind() != reflect.Func || handlerValue.IsNil() {
		panic("fiber: Config.RegexHandler must be a non-nil function")
	}
	if handlerType.NumIn() != 1 || handlerType.In(0) != stringType || handlerType.NumOut() != 1 {
		panic("fiber: Config.RegexHandler must have signature func(string) T")
	}
	if !handlerType.Out(0).Implements(regexMatcherType) {
		panic("fiber: Config.RegexHandler return type must support MatchString(string) bool")

View on GitHub (pinned to 9a4c7e57fe)

Solutions

Return a real compiled matcher from RegexHandler for every input (regexp.MustCompile never returns nil - it panics on bad patterns instead).
If your wrapper can fail, validate the pattern and panic/return a non-nil zero matcher rather than nil.
Use the default regexp.MustCompile which guarantees a non-nil *regexp.Regexp.

Example fix

// before
app := fiber.New(fiber.Config{
    RegexHandler: func(p string) *regexp.Regexp { return nil },
})
app.Get("/:v<regex(\\d+)>", h)

// after
app := fiber.New(fiber.Config{
    RegexHandler: regexp.MustCompile, // never returns nil
})

Defensive patterns

Strategy: validation

Validate before calling

// Wrap so a nil result is impossible.
safeHandler := func(p string) *regexp.Regexp {
    re := regexp.MustCompile(p) // panics on bad pattern instead of returning nil
    return re
}
_ = fiber.New(fiber.Config{RegexHandler: safeHandler})

Prevention

Use regexp.MustCompile, which never returns nil.
If wrapping, forward the compiled matcher or panic on failure - never return nil.
Unit-test the handler against the patterns your routes actually use.

When it happens

Trigger: Config.RegexHandler returns nil for an input pattern, e.g. func(string) *regexp.Regexp { return nil }, combined with any route using regex(...) (constraint.go:549 path). Pattern-specific failures where the handler returns nil instead of an error also hit this.

Common situations: A stub/mock handler that returns nil; a custom compiler that swallows compile errors and returns nil; refactoring regexp.MustCompile into a wrapper that forgot to forward the result.

Related errors

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