{"record":{"id":"2e9824269602f1d1","repo":"caddyserver/caddy","slug":"loading-event-subscriber-modules-v","errorCode":null,"errorMessage":"loading event subscriber modules: %v","messagePattern":"loading event subscriber modules: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyevents/app.go","lineNumber":130,"sourceCode":"func (App) CaddyModule() caddy.ModuleInfo {\n\treturn caddy.ModuleInfo{\n\t\tID:  \"events\",\n\t\tNew: func() caddy.Module { return new(App) },\n\t}\n}\n\n// Provision sets up the app.\nfunc (app *App) Provision(ctx caddy.Context) error {\n\tapp.logger = ctx.Logger()\n\tapp.subscriptions = make(map[string]map[caddy.ModuleID][]Handler)\n\n\tfor _, sub := range app.Subscriptions {\n\t\tif sub.HandlersRaw == nil {\n\t\t\tcontinue\n\t\t}\n\t\thandlersIface, err := ctx.LoadModule(sub, \"HandlersRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading event subscriber modules: %v\", err)\n\t\t}\n\t\tfor _, h := range handlersIface.([]any) {\n\t\t\tsub.Handlers = append(sub.Handlers, h.(Handler))\n\t\t}\n\t\tif len(sub.Handlers) == 0 {\n\t\t\t// pointless to bind without any handlers\n\t\t\treturn fmt.Errorf(\"no handlers defined\")\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// Start runs the app.\nfunc (app *App) Start() error {\n\tfor _, sub := range app.Subscriptions {\n\t\tif err := app.Subscribe(sub); err != nil {\n\t\t\treturn err","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyevents/app.go#L112-L148","documentation":"The events app's Provision loads each subscription's HandlersRaw via ctx.LoadModule; any failure in resolving, provisioning, or validating an event handler module (modules under caddy.events.handlers.*) is wrapped with this message.","triggerScenarios":"An events subscription with handlers whose module name is not registered (e.g. a third-party event handler not built in) or whose inline config fails its own provisioning.","commonSituations":"xcaddy builds missing the events plugin; typos in the handler module name; JSON event configs with wrong inline keys; plugin API changes across Caddy versions breaking the handler's Provision.","solutions":["Read the wrapped error to distinguish 'module not registered' from handler-level provisioning failures.","Fix or rebuild: include the plugin via xcaddy, or correct the handler name/config.","Run 'caddy list-modules | grep caddy.events' to see available event handler modules in your binary.","Validate with 'caddy validate --config ...' before deploying."],"exampleFix":"// before (caddyfile)\n{\n    events {\n        on tls cert_obtained {\n            handler nonexistent\n        }\n    }\n}\n\n// after (use a handler that exists in your build, or remove the block)\n{\n    events {\n        on tls cert_obtained {\n            handler exec {\n                command echo obtained\n            }\n        }\n    }\n}","handlingStrategy":"validation","validationCode":"// before load, confirm every referenced event handler module exists\nfor _, id := range eventHandlerModuleIDs(cfg) {\n    if _, err := caddy.GetModule(id); err != nil {\n        return fmt.Errorf(\"event handler %s not in build: %w\", id, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := caddy.Validate(cfg); err != nil {\n    if strings.Contains(err.Error(), \"loading event subscriber modules\") {\n        // nested cause identifies the handler; fix module id or rebuild\n    }\n    return err\n}","preventionTips":["Validate configs containing events blocks with the production binary.","Pin event-handler plugin versions in the xcaddy build.","Check 'caddy list-modules | grep caddy.events.handlers' after builds."],"tags":["events","module-system","provisioning"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}