{"record":{"id":"cd5fc0b7a4aeabbd","repo":"caddyserver/caddy","slug":"client-auth-mode-not-recognized-s","errorCode":null,"errorMessage":"client auth mode not recognized: %s","messagePattern":"client auth mode not recognized: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/connpolicy.go","lineNumber":853,"sourceCode":"\t// if there's no actionable client auth, simply disable it\n\tif !clientauth.Active() {\n\t\tcfg.ClientAuth = tls.NoClientCert\n\t\treturn nil\n\t}\n\n\t// enforce desired mode of client authentication\n\tif len(clientauth.Mode) > 0 {\n\t\tswitch clientauth.Mode {\n\t\tcase \"request\":\n\t\t\tcfg.ClientAuth = tls.RequestClientCert\n\t\tcase \"require\":\n\t\t\tcfg.ClientAuth = tls.RequireAnyClientCert\n\t\tcase \"verify_if_given\":\n\t\t\tcfg.ClientAuth = tls.VerifyClientCertIfGiven\n\t\tcase \"require_and_verify\":\n\t\t\tcfg.ClientAuth = tls.RequireAndVerifyClientCert\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"client auth mode not recognized: %s\", clientauth.Mode)\n\t\t}\n\t} else {\n\t\t// otherwise, set a safe default mode\n\t\tif len(clientauth.TrustedCACerts) > 0 ||\n\t\t\tlen(clientauth.TrustedCACertPEMFiles) > 0 ||\n\t\t\tlen(clientauth.TrustedLeafCerts) > 0 ||\n\t\t\tclientauth.CARaw != nil || clientauth.ca != nil {\n\t\t\tcfg.ClientAuth = tls.RequireAndVerifyClientCert\n\t\t} else {\n\t\t\tcfg.ClientAuth = tls.RequireAnyClientCert\n\t\t}\n\t}\n\n\t// enforce CA verification by adding CA certs to the ClientCAs pool\n\tif clientauth.ca != nil {\n\t\tcfg.ClientCAs = clientauth.ca.CertPool()\n\t}\n","sourceCodeStart":835,"sourceCodeEnd":871,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/connpolicy.go#L835-L871","documentation":"ClientAuthentication.Configure sets the Go TLS ClientAuth mode from clientauth.Mode; only four strings are accepted: request, require, verify_if_given, require_and_verify. Anything else fails handshake configuration. If Mode is empty a safe default is derived from whether trust material (CA certs, verifiers, or a CA module) is present.","triggerScenarios":"Typing an invalid mode string into client_auth { mode ... } in a Caddyfile or the \"mode\" JSON field, e.g. 'require_verify', 'optional', 'verify', 'none', or a quoted JSON value with different casing like 'Require'.","commonSituations":"Migrating from nginx ('ssl_verify_client optional' has no 1:1 name here — the equivalent is verify_if_given) or from old Caddy versions/docs; autocomplete or memory producing plausible-but-wrong mode names.","solutions":["Change the mode to one of exactly: request, require, verify_if_given, require_and_verify","Map from nginx semantics: none->(omit), optional->request, optional_no_ca->verify_if_given, on->require_and_verify","Run caddy validate --config <file> to catch it before restart"],"exampleFix":"# before\nclient_auth {\n  mode optional\n}\n\n# after\nclient_auth {\n  mode verify_if_given\n}","handlingStrategy":"validation","validationCode":"var validClientAuthModes = map[string]bool{\n\t\"request\": true, \"require\": true,\n\t\"verify_if_given\": true, \"require_and_verify\": true,\n}\nfunc validateMode(mode string) error {\n\tif !validClientAuthModes[mode] {\n\t\treturn fmt.Errorf(\"invalid client auth mode %q; want one of request, require, verify_if_given, require_and_verify\", mode)\n\t}\n\treturn nil\n}","typeGuard":"func isValidClientAuthMode(mode string) bool {\n\tswitch mode {\n\tcase \"request\", \"require\", \"verify_if_given\", \"require_and_verify\":\n\t\treturn true\n\t}\n\treturn false\n}","tryCatchPattern":null,"preventionTips":["Keep a fleet-wide mapping from nginx ssl_verify_client values to Caddy modes","Template client_auth blocks from one tested snippet instead of hand-typing modes","Validate configs in CI: caddy validate --adapter caddyfile --config Caddyfile"],"tags":["tls","client-auth","config","validation"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}