{"record":{"id":"834abecefbb1fbc0","repo":"caddyserver/caddy","slug":"getting-matcher-module-s-v","errorCode":null,"errorMessage":"getting matcher module '%s': %v","messagePattern":"getting matcher module '(.+?)': (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"caddyconfig/httpcaddyfile/httptype.go","lineNumber":1695,"sourceCode":"\tif _, ok := matchers[definitionName]; ok {\n\t\treturn fmt.Errorf(\"matcher is defined more than once: %s\", definitionName)\n\t}\n\tmatchers[definitionName] = make(caddy.ModuleMap)\n\n\t// given a matcher name and the tokens following it, parse\n\t// the tokens as a matcher module and record it\n\tmakeMatcher := func(matcherName string, tokens []caddyfile.Token) error {\n\t\t// create a new dispenser from the tokens\n\t\tdispenser := caddyfile.NewDispenser(tokens)\n\n\t\t// set the matcher name (without @) in the dispenser context so\n\t\t// that matcher modules can access it to use it as their name\n\t\t// (e.g. regexp matchers which use the name for capture groups)\n\t\tdispenser.SetContext(caddyfile.MatcherNameCtxKey, definitionName[1:])\n\n\t\tmod, err := caddy.GetModule(\"http.matchers.\" + matcherName)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"getting matcher module '%s': %v\", matcherName, err)\n\t\t}\n\t\tunm, ok := mod.New().(caddyfile.Unmarshaler)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"matcher module '%s' is not a Caddyfile unmarshaler\", matcherName)\n\t\t}\n\t\terr = unm.UnmarshalCaddyfile(dispenser)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif rm, ok := unm.(caddyhttp.RequestMatcherWithError); ok {\n\t\t\tmatchers[definitionName][matcherName] = caddyconfig.JSON(rm, nil)\n\t\t\treturn nil\n\t\t}\n\t\t// nolint:staticcheck\n\t\tif rm, ok := unm.(caddyhttp.RequestMatcher); ok {\n\t\t\tmatchers[definitionName][matcherName] = caddyconfig.JSON(rm, nil)\n\t\t\treturn nil","sourceCodeStart":1677,"sourceCodeEnd":1713,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/caddyconfig/httpcaddyfile/httptype.go#L1677-L1713","documentation":"Thrown while adapting a Caddyfile when a named matcher definition (e.g. '@mymatch { ... }') references a matcher module that is not registered under the 'http.matchers.' namespace. caddy.GetModule fails, so the adapter cannot instantiate the matcher. This almost always means the matcher name is misspelled or the build does not include the plugin providing that matcher.","triggerScenarios":"Writing '@myMatcher header_regexp ...' with a typo like '@myMatcher header_regex ...'; using a matcher provided by a third-party plugin in a binary built without that plugin; referencing an experimental matcher renamed between Caddy versions.","commonSituations":"Custom/xcaddy builds where a plugin was dropped from the build list; upgrading Caddy without rebuilding plugins; Caddyfiles copied from docs of a plugin the user never installed; typo in a matcher name inside a named matcher block.","solutions":["Check the exact spelling of the matcher name against the Caddyfile matcher docs (header, header_regexp, path, path_regexp, method, query, expression, remote_ip, client_ip, protocol, file, not, vars, ...).","If the matcher comes from a plugin, verify it is in the build: 'caddy list-modules' and look under http.matchers.","Rebuild with 'xcaddy build --with <plugin-module-path>' and retry adapt/run.","If upgrading, read the plugin's changelog for matcher renames and update the Caddyfile."],"exampleFix":"# before\n@api path_regex ^/api/(.*)\n\n# after\n@api path_regexp ^/api/(.*)","handlingStrategy":"validation","validationCode":"# before adapting/running, confirm the matcher is registered\ncaddy list-modules 2>/dev/null | grep -q '^http.matchers.header_regexp$' && echo ok || echo 'matcher missing from build'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run 'caddy adapt --config Caddyfile --adapter caddyfile' in CI to catch adapt-time errors before deploy.","Pin plugin versions and rebuild the whole binary with xcaddy whenever core is upgraded.","Keep a checked-in list of required plugins next to the Caddyfile."],"tags":["caddyfile","matcher","module-registration","config-adapt"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}