{"record":{"id":"4ecf8c1c29ff76a1","repo":"caddyserver/caddy","slug":"module-not-registered-s","errorCode":null,"errorMessage":"module not registered: %s","messagePattern":"module not registered: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules.go","lineNumber":169,"sourceCode":"\t\tpanic(\"ModuleInfo.New must return a non-nil module instance\")\n\t}\n\n\tmodulesMu.Lock()\n\tdefer modulesMu.Unlock()\n\n\tif _, ok := modules[string(mod.ID)]; ok {\n\t\tpanic(fmt.Sprintf(\"module already registered: %s\", mod.ID))\n\t}\n\tmodules[string(mod.ID)] = mod\n}\n\n// GetModule returns module information from its ID (full name).\nfunc GetModule(name string) (ModuleInfo, error) {\n\tmodulesMu.RLock()\n\tdefer modulesMu.RUnlock()\n\tm, ok := modules[name]\n\tif !ok {\n\t\treturn ModuleInfo{}, fmt.Errorf(\"module not registered: %s\", name)\n\t}\n\treturn m, nil\n}\n\n// GetModuleName returns a module's name (the last label of its ID)\n// from an instance of its value. If the value is not a module, an\n// empty string will be returned.\nfunc GetModuleName(instance any) string {\n\tvar name string\n\tif mod, ok := instance.(Module); ok {\n\t\tname = mod.CaddyModule().ID.Name()\n\t}\n\treturn name\n}\n\n// GetModuleID returns a module's ID from an instance of its value.\n// If the value is not a module, an empty string will be returned.\nfunc GetModuleID(instance any) string {","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules.go#L151-L187","documentation":"caddy.GetModule(name) looks a module up by its full namespaced ID in the global registry; if no module with that exact ID was registered at init time, it returns this error. Registration happens only for packages compiled into the binary.","triggerScenarios":"Calling caddy.GetModule with a misspelled or non-existent module ID; looking up a standard module in a custom build that does not import modules/standard; looking up a plugin module without having built with xcaddy.","commonSituations":"Custom minimal builds that omit standard imports; code or configs referencing a module renamed between Caddy versions; plugins looked up by short name instead of full ID (e.g. 'file_server' instead of 'http.handlers.file_server').","solutions":["Use the full module ID including namespace: 'http.handlers.file_server', not 'file_server'.","Run 'caddy list-modules' in the actual binary to see what is registered.","For custom builds, import the package (blank import if needed) so its init() registers the module, or rebuild via xcaddy with the plugin.","Check the module ID against the docs for your Caddy version — IDs occasionally change across majors."],"exampleFix":"// before\ninfo, err := caddy.GetModule(\"file_server\")\n\n// after\ninfo, err := caddy.GetModule(\"http.handlers.file_server\")","handlingStrategy":"validation","validationCode":"// check registration before use\nif _, err := caddy.GetModule(fullModuleID); err != nil {\n    return fmt.Errorf(\"build is missing module %s — rebuild with xcaddy or fix the ID: %w\", fullModuleID, err)\n}","typeGuard":null,"tryCatchPattern":"info, err := caddy.GetModule(id)\nif err != nil {\n    if strings.Contains(err.Error(), \"module not registered\") {\n        // fall back to a registered alternative or fail the run with a clear message\n    }\n    return err\n}","preventionTips":["Use full namespaced IDs, never short names.","Assert required modules exist at startup via caddy.GetModule guards.","Keep 'caddy list-modules' output in version control next to the build recipe."],"tags":["module-system","registration","build"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}