{"record":{"id":"395caedba6982da3","repo":"caddyserver/caddy","slug":"module-name-s-v","errorCode":null,"errorMessage":"module name '%s': %v","messagePattern":"module name '(.+?)': (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"context.go","lineNumber":347,"sourceCode":"\t}\n\treturn mods, nil\n}\n\n// loadModuleMap loads modules from a ModuleMap, i.e. map[string]any, where the key is the\n// module name. With a module map, module names do not need to be defined inline with their values.\nfunc (ctx Context) loadModuleMap(namespace string, val reflect.Value) (map[string]any, error) {\n\tall := make(map[string]any)\n\titer := val.MapRange()\n\tfor iter.Next() {\n\t\tk := iter.Key().Interface().(string)\n\t\tv := iter.Value().Interface().(json.RawMessage)\n\t\tmoduleName := namespace + \".\" + k\n\t\tif namespace == \"\" {\n\t\t\tmoduleName = k\n\t\t}\n\t\tval, err := ctx.LoadModuleByID(moduleName, v)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"module name '%s': %v\", k, err)\n\t\t}\n\t\tall[k] = val\n\t}\n\treturn all, nil\n}\n\n// LoadModuleByID decodes rawMsg into a new instance of mod and\n// returns the value. If mod.New is nil, an error is returned.\n// If the module implements Validator or Provisioner interfaces,\n// those methods are invoked to ensure the module is fully\n// configured and valid before being used.\n//\n// This is a lower-level method and will usually not be called\n// directly by most modules. However, this method is useful when\n// dynamically loading/unloading modules in their own context,\n// like from embedded scripts, etc.\nfunc (ctx Context) LoadModuleByID(id string, rawMsg json.RawMessage) (any, error) {\n\tmodulesMu.RLock()","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/context.go#L329-L365","documentation":"loadModuleMap handles fields typed caddy.ModuleMap (map[string]json.RawMessage) where the MAP KEY is the module name (namespace already implied by the field's caddy tag). It calls ctx.LoadModuleByID(namespace+\".\"+key, value) per entry; any failure is wrapped as \"module name '%s': %v\" naming the map key. The inner error is usually 'unknown module', a decode failure, or a provision/validate failure.","triggerScenarios":"A struct field of type caddy.ModuleMap tagged caddy:\"module=namespace\"; during LoadModule, an entry's key resolves to namespace.key which is not registered, or its JSON value fails StrictUnmarshalJSON/Provision/Validate, producing fmt.Errorf(\"module name '%s': %v\", k, err).","commonSituations":"Using a DNS provider module (e.g. acme_dns) whose plugin is not compiled into the binary; misspelling the module name as the map key; a config written for a newer Caddy version using a module name that does not exist in the installed one.","solutions":["Check the module name given in quotes against `caddy list-modules --packages` output for the expected namespace","If the module comes from a plugin, rebuild with `xcaddy build --with <plugin@version>` or use a Caddy build that includes it","Fix the JSON body of that entry if the inner error mentions decoding or provisioning","Align config and binary versions: configs adapted by/for newer Caddy versions may reference renamed modules"],"exampleFix":"// before\n\"dns_challenge\": { \"cloudfare\": {} } // typo in module name key\n// after\n\"dns_challenge\": { \"cloudflare\": { \"api_token\": \"{env.CF_TOKEN}\" } }","handlingStrategy":"validation","validationCode":"// Verify each ModuleMap key resolves to a registered module before load\nmods := caddy.GetModules(\"dns\") // or the relevant namespace\nfor name := range moduleMap {\n    if _, ok := mods[name]; !ok {\n        return fmt.Errorf(\"module name '%s' not registered in namespace\", name)\n    }\n}","typeGuard":"func moduleRegistered(id string) bool {\n    for _, m := range caddy.Modules() { if m == id { return true } }\n    return false\n}","tryCatchPattern":"if _, err := ctx.LoadModule(field, raw); err != nil { return fmt.Errorf(\"%s: %w\", field, err) } // 'module name K:' names the key","preventionTips":["Cross-check ModuleMap keys against `caddy list-modules` output","Build custom binaries with xcaddy including all plugins referenced by config","Keep config and binary versions in lockstep"],"tags":["caddy","module-system","config","registration"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}