{"record":{"id":"bf02bda1bcef73f8","repo":"caddyserver/caddy","slug":"loading-identity-issuer-modules-s","errorCode":null,"errorMessage":"loading identity issuer modules: %s","messagePattern":"loading identity issuer modules: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"admin.go","lineNumber":478,"sourceCode":"// manageIdentity sets up automated identity management for this server.\nfunc manageIdentity(ctx Context, cfg *Config) error {\n\tif cfg == nil || cfg.Admin == nil || cfg.Admin.Identity == nil {\n\t\treturn nil\n\t}\n\n\t// set default issuers; this is pretty hacky because we can't\n\t// import the caddytls package -- but it works\n\tif cfg.Admin.Identity.IssuersRaw == nil {\n\t\tcfg.Admin.Identity.IssuersRaw = []json.RawMessage{\n\t\t\tjson.RawMessage(`{\"module\": \"acme\"}`),\n\t\t}\n\t}\n\n\t// load and provision issuer modules\n\tif cfg.Admin.Identity.IssuersRaw != nil {\n\t\tval, err := ctx.LoadModule(cfg.Admin.Identity, \"IssuersRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading identity issuer modules: %s\", err)\n\t\t}\n\t\tfor _, issVal := range val.([]any) {\n\t\t\tcfg.Admin.Identity.issuers = append(cfg.Admin.Identity.issuers, issVal.(certmagic.Issuer))\n\t\t}\n\t}\n\n\t// we'll make a new cache when we make the CertMagic config, so stop any previous cache\n\tif identityCertCache != nil {\n\t\tidentityCertCache.Stop()\n\t}\n\n\tlogger := Log().Named(\"admin.identity\")\n\tcmCfg := cfg.Admin.Identity.certmagicConfig(logger, true)\n\n\t// issuers have circular dependencies with the configs because,\n\t// as explained in the caddytls package, they need access to the\n\t// correct storage and cache to solve ACME challenges\n\tfor _, issuer := range cfg.Admin.Identity.issuers {","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/admin.go#L460-L496","documentation":"Raised during admin identity configuration when ctx.LoadModule fails to load/provision the configured identity issuer modules (cfg.Admin.Identity.IssuersRaw). The inner error usually names the exact module and problem — unknown module name, invalid issuer JSON, or issuer provisioning failure. Defaults to an 'acme' issuer if none configured.","triggerScenarios":"Configuring admin.identity with a custom issuers array in JSON where the 'module' field names a nonexistent issuer; malformed issuer JSON; an ACME issuer whose Provision fails (e.g. invalid fields); custom issuer plugins not compiled into the binary.","commonSituations":"Using the experimental remote admin feature with identity issuers; typo in module name ('acme' vs 'acme_dns'); plugin modules missing from custom builds; schema changes between Caddy versions.","solutions":["Inspect the wrapped error — it identifies which issuer module and why it failed","Verify each issuer object has a valid 'module' key matching a registered issuer (e.g. 'acme', 'internal', 'zerossl')","For plugin issuers, rebuild with xcaddy ensuring the plugin is included and compatible","Simplify: omit issuers_raw to use the default ACME identity issuer and see if the error disappears"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"var knownIssuers = map[string]bool{\"acme\": true, \"internal\": true, \"zerossl\": true}\n\nfunc validateIdentityIssuers(cfg []json.RawMessage) error {\n\tfor _, raw := range cfg {\n\t\tvar probe struct{ Module string `json:\"module\"` }\n\t\tif err := json.Unmarshal(raw, &probe); err != nil {\n\t\t\treturn fmt.Errorf(\"issuer JSON invalid: %v\", err)\n\t\t}\n\t\tif !knownIssuers[probe.Module] {\n\t\t\treturn fmt.Errorf(\"unknown issuer module %q (is the plugin built in?)\", probe.Module)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate issuer module names against registered caddy modules (caddy list-modules)","Omit issuers_raw to use the default ACME identity issuer when unsure","Rebuild xcaddy binaries after adding issuer plugins"],"tags":["admin-api","identity","modules","configuration"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}