api container: set dependency matcher: fn cannot be nil

Error message

api container: set dependency matcher: fn cannot be nil

What it means

APIContainer.SetDependencyMatcher replaces the function that decides whether a hero dependency matches an input (struct field or function parameter). A nil fn would break every subsequent dependency resolution, so the method panics when fn is nil. Defaults to hero.DefaultMatchDependencyFunc if never called.

Source

Thrown at core/router/api_container.go:112

	api.Container.MarkExportedFieldsAsRequired = strictMode
	return api
}

// EnableStructDependents sets the container's EnableStructDependents to true.
// It's used to automatically fill the dependencies of a struct's fields
// based on the previous registered dependencies, just like function inputs.
func (api *APIContainer) EnableStructDependents() *APIContainer {
	api.Container.EnableStructDependents = true
	return api
}

// SetDependencyMatcher replaces the function that compares equality between
// a dependency and an input (struct field or function parameter).
//
// Defaults to hero.DefaultMatchDependencyFunc.
func (api *APIContainer) SetDependencyMatcher(fn hero.DependencyMatcher) *APIContainer {
	if fn == nil {
		panic("api container: set dependency matcher: fn cannot be nil")
	}

	api.Container.DependencyMatcher = fn
	return api
}

// convertHandlerFuncs accepts Iris hero handlers and returns a slice of native Iris handlers.
func (api *APIContainer) convertHandlerFuncs(relativePath string, handlersFn ...any) context.Handlers {
	fullpath := api.Self.GetRelPath() + relativePath
	paramsCount := macro.CountParams(fullpath, *api.Self.Macros())

	handlers := make(context.Handlers, 0, len(handlersFn))
	for _, h := range handlersFn {
		handlers = append(handlers, api.Container.HandlerWithParams(h, paramsCount))
	}

	// Note: let end-developer to decide that through Party.SetExecutionRules.
	// On that type of handlers the end-developer does not have to include the Context in the handler,

View on GitHub (pinned to 7bedaf55a0)

Solutions

Pass a non-nil hero.DependencyMatcher implementation to SetDependencyMatcher
To restore default behavior, set hero.DefaultMatchDependencyFunc explicitly instead of nil
Guard the value before calling: if fn != nil { api.SetDependencyMatcher(fn) }

Example fix

// before
var matcher hero.DependencyMatcher
api.SetDependencyMatcher(matcher) // panics: fn cannot be nil
// after
api.SetDependencyMatcher(hero.DefaultMatchDependencyFunc) // or a custom non-nil matcher

Defensive patterns

Strategy: validation

Validate before calling

func safeSetDependencyMatcher(api *iris.APIContainer, fn hero.DependencyMatcher) *iris.APIContainer {
    if fn == nil {
        fn = hero.DefaultMatchDependencyFunc
    }
    return api.SetDependencyMatcher(fn)
}

Type guard

func isMatcherSet(fn hero.DependencyMatcher) bool {
    return fn != nil
}

Try / catch

func setMatcherSafe(api *iris.APIContainer, fn hero.DependencyMatcher) {
    defer func() {
        if r := recover(); r != nil {
            log.Fatalf("SetDependencyMatcher panicked: %v", r)
        }
    }()
    api.SetDependencyMatcher(fn)
}

Prevention

Never pass nil; fall back to hero.DefaultMatchDependencyFunc to reset behavior
Validate that registry/config lookups for custom matchers return non-nil
Set the matcher once during app bootstrap, before hero dependency resolution

When it happens

Trigger: Calling APIContainer.SetDependencyMatcher(nil), typically with a variable of type hero.DependencyMatcher that was declared but never assigned, or a lookup of a custom matcher function that returned nil.

Common situations: Building custom DI matchers where the matcher is fetched from a registry/config and can be nil; typos where the result of the assignment was discarded; attempting to "reset" the matcher by passing nil instead of restoring hero.DefaultMatchDependencyFunc.

Related errors

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/9508de9c18871eb4. Report an issue: GitHub.