{"record":{"id":"0ca723014ac6701e","repo":"caddyserver/caddy","slug":"loading-certificates-v","errorCode":null,"errorMessage":"loading certificates: %v","messagePattern":"loading certificates: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/tls.go","lineNumber":266,"sourceCode":"\t// manual/static (unmanaged) certificates - we do this in\n\t// provision so that other apps (such as http) can know which\n\t// certificates have been manually loaded, and also so that\n\t// commands like validate can be a better test\n\tcertCacheMu.RLock()\n\tmagic := certmagic.New(certCache, certmagic.Config{\n\t\tStorage: ctx.Storage(),\n\t\tLogger:  t.logger,\n\t\tOnEvent: t.onEvent,\n\t\tOCSP: certmagic.OCSPConfig{\n\t\t\tDisableStapling: t.DisableOCSPStapling,\n\t\t},\n\t\tDisableStorageCheck: t.DisableStorageCheck,\n\t})\n\tcertCacheMu.RUnlock()\n\tfor _, loader := range t.certificateLoaders {\n\t\tcerts, err := loader.LoadCertificates()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading certificates: %v\", err)\n\t\t}\n\t\tfor _, cert := range certs {\n\t\t\thash, err := magic.CacheUnmanagedTLSCertificate(ctx, cert.Certificate, cert.Tags)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"caching unmanaged certificate: %v\", err)\n\t\t\t}\n\t\t\tt.loaded[hash] = \"\"\n\t\t}\n\t}\n\n\t// on-demand permission module\n\tif t.Automation != nil && t.Automation.OnDemand != nil && t.Automation.OnDemand.PermissionRaw != nil {\n\t\tif t.Automation.OnDemand.Ask != \"\" {\n\t\t\treturn fmt.Errorf(\"on-demand TLS config conflict: both 'ask' endpoint and a 'permission' module are specified; 'ask' is deprecated, so use only the permission module\")\n\t\t}\n\t\tval, err := ctx.LoadModule(t.Automation.OnDemand, \"PermissionRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading on-demand TLS permission module: %v\", err)","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/tls.go#L248-L284","documentation":"After all certificate loader modules are provisioned, each loader's LoadCertificates() is called to actually read the certificates from disk (or elsewhere). This error wraps a loader failure: files that do not exist, are unreadable due to permissions, or are not parseable as PEM-encoded certificate/key pairs.","triggerScenarios":"load_files pointing to a certificate or key path that does not exist or has wrong ownership/mode; PEM blocks that are truncated, binary (DER instead of PEM), or whose key does not match the certificate; load_folders containing corrupt files.","commonSituations":"Cert files mounted into a container at a different path than configured; permissions changed after a system update; cert/key regenerated by another tool in DER format; copy-pasting certs introducing whitespace/truncation.","solutions":["Read the wrapped error: it comes from the specific loader and usually names the offending file","Verify paths exist and are readable by the Caddy process user (check mount points in containers)","Validate PEM format: 'openssl x509 -in cert.pem -noout' and 'openssl pkey -in key.pem -noout' must succeed","Confirm cert/key pair matches: compare modulus or use 'openssl x509 -noout -modulus' vs 'openssl rsa -noout -modulus'"],"exampleFix":"# before\nload_files: certificate=/etc/cert/example.pem (file missing)\n# after: point to the real path and verify\n$ openssl x509 -in /etc/ssl/example.com/cert.pem -noout\n{\"load_files\": [{\"certificate\": \"/etc/ssl/example.com/cert.pem\", \"key\": \"/etc/ssl/example.com/key.pem\"}]}","handlingStrategy":"validation","validationCode":"for f in /certs/cert.pem /certs/key.pem; do\n  test -r \"$f\" || echo \"unreadable: $f\"\n  openssl x509 -in \"$f\" -noout >/dev/null 2>&1 || openssl pkey -in \"$f\" -noout >/dev/null 2>&1 || echo \"not PEM: $f\"\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check cert/key readability and PEM parseability in your deployment scripts before starting Caddy","Mount certs into containers at fixed paths and reference those paths"],"tags":["caddy","tls","certificates","filesystem","pem"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}