{"record":{"id":"9858936e92e0d5d4","repo":"caddyserver/caddy","slug":"provisioning-admin-router-module-s-v","errorCode":null,"errorMessage":"provisioning admin router module %s: %v","messagePattern":"provisioning admin router module (.+?): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"admin.go","lineNumber":283,"sourceCode":"\taddRoute(\"/stop\", handlerLabel, AdminHandlerFunc(handleStop))\n\n\t// register debugging endpoints\n\taddRouteWithMetrics(\"/debug/pprof/\", handlerLabel, http.HandlerFunc(pprof.Index))\n\taddRouteWithMetrics(\"/debug/pprof/cmdline\", handlerLabel, http.HandlerFunc(pprof.Cmdline))\n\taddRouteWithMetrics(\"/debug/pprof/profile\", handlerLabel, http.HandlerFunc(pprof.Profile))\n\taddRouteWithMetrics(\"/debug/pprof/symbol\", handlerLabel, http.HandlerFunc(pprof.Symbol))\n\taddRouteWithMetrics(\"/debug/pprof/trace\", handlerLabel, http.HandlerFunc(pprof.Trace))\n\taddRouteWithMetrics(\"/debug/vars\", handlerLabel, expvar.Handler())\n\n\t// register third-party module endpoints\n\tfor _, m := range GetModules(\"admin.api\") {\n\t\trouter := m.New().(AdminRouter)\n\n\t\t// provision the router before registering its routes, so\n\t\t// handlers have access to all provisioned state\n\t\tif provisioner, ok := router.(Provisioner); ok {\n\t\t\tif err := provisioner.Provision(ctx); err != nil {\n\t\t\t\treturn adminHandler{}, fmt.Errorf(\"provisioning admin router module %s: %v\", m.ID, err)\n\t\t\t}\n\t\t}\n\n\t\tfor _, route := range router.Routes() {\n\t\t\taddRoute(route.Pattern, handlerLabel, route.Handler)\n\t\t}\n\t}\n\n\treturn muxWrap, nil\n}\n\n// allowedOrigins returns a list of origins that are allowed.\n// If admin.Origins is nil (null), the provided listen address\n// will be used as the default origin. If admin.Origins is\n// empty, no origins will be allowed, effectively bricking the\n// endpoint for non-unix-socket endpoints, but whatever.\nfunc (admin AdminConfig) allowedOrigins(addr NetworkAddress) []*url.URL {\n\tuniqueOrigins := make(map[string]struct{})","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/admin.go#L265-L301","documentation":"While building the admin endpoint's route table, Caddy iterates all modules in the 'admin.api' namespace and calls Provision on those implementing Provisioner. If any such module fails provisioning, startup aborts with this wrapper including the module ID and the underlying error. The wrapped error (e.g. 'no metrics registry found') carries the real cause.","triggerScenarios":"Any admin.api.* module whose Provision returns an error: admin.api.metrics with a missing registry, third-party admin routers with invalid config, custom plugins registered under admin.api failing to provision.","commonSituations":"Installing a third-party admin API plugin with a bad or missing config block; enabling the metrics admin endpoint in a config that doesn't initialize the registry; plugin version incompatibility after upgrading Caddy.","solutions":["Read the '%s: %v' suffix — the module ID names the failing module and the inner error the cause; fix that module's config","Remove or correct the offending admin.api module from the config","For plugins, check compatibility with your Caddy version and rebuild xcaddy build with matching versions","Validate with caddy validate --config to catch it before restart"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := adminConfigProvision(cfg); err != nil {\n    var apiErr caddy.APIError\n    if errors.As(err, &apiErr) {\n        log.Printf(\"admin module provisioning failed: status=%d err=%v\", apiErr.HTTPStatus, apiErr.Err)\n    }\n    // fall back to last-known-good config\n}","preventionTips":["Run caddy validate on any config adding or updating admin.api modules","Keep plugins under admin.api.* in sync with the Caddy core version","Read the wrapped module ID in the error to pinpoint the failing module"],"tags":["admin-api","provisioning","plugins","startup"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}