{"record":{"id":"ca1b65db6b86a167","repo":"caddyserver/caddy","slug":"provisioning-ca-s-v","errorCode":null,"errorMessage":"provisioning CA '%s': %v","messagePattern":"provisioning CA '(.+?)': (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"modules/caddypki/pki.go","lineNumber":63,"sourceCode":"}\n\n// CaddyModule returns the Caddy module information.\nfunc (PKI) CaddyModule() caddy.ModuleInfo {\n\treturn caddy.ModuleInfo{\n\t\tID:  \"pki\",\n\t\tNew: func() caddy.Module { return new(PKI) },\n\t}\n}\n\n// Provision sets up the configuration for the PKI app.\nfunc (p *PKI) Provision(ctx caddy.Context) error {\n\tp.ctx = ctx\n\tp.log = ctx.Logger()\n\n\tfor caID, ca := range p.CAs {\n\t\terr := ca.Provision(ctx, caID, p.log)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"provisioning CA '%s': %v\", caID, err)\n\t\t}\n\t}\n\n\t// if this app is initialized at all, ensure there's at\n\t// least a default CA that can be used: the standard CA\n\t// which is used implicitly for signing local-use certs\n\tif len(p.CAs) == 0 {\n\t\terr := p.ProvisionDefaultCA(ctx)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"provisioning CA '%s': %v\", DefaultCAID, err)\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// ProvisionDefaultCA sets up the default CA.\nfunc (p *PKI) ProvisionDefaultCA(ctx caddy.Context) error {","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddypki/pki.go#L45-L81","documentation":"Returned by PKI.Provision (modules/caddypki/pki.go:63) when provisioning a CA explicitly declared in the pki app configuration fails. It wraps whatever CA.Provision produced: unreadable or malformed root/intermediate files, keystore errors, key/cert mismatches, or bad names/durations in the CA config. This is a startup-time failure: Caddy refuses to start with the given config.","triggerScenarios":"Declaring pki { ca <id> { ... } } with root/intermediate blocks whose cert_file/key_file paths are wrong, whose PEM content is invalid, or whose key does not match the certificate; a duplicate or reserved CA ID; a custom storage-backed keystore that cannot be opened.","commonSituations":"Path typos or container-relative paths that differ inside the container; files mounted read-only at the wrong location; PEM files with Windows line endings or trailing garbage; using a symlink that resolves outside the allowed directory; YAML/JSON indentation mistakes that put CA options under the wrong block.","solutions":["Read the wrapped error - it names the concrete failure (file read, PEM decode, key mismatch, etc.) and fix that first","Verify every path you configured actually exists and is readable by the Caddy process: sudo -u caddy cat <path>","Validate the PEM pair: openssl x509 -in cert.pem -noout && openssl pkey -in key.pem -noout && match the public keys","Simplify: temporarily remove the root/intermediate blocks so Caddy generates its own CA, confirming the rest of the config is sound, then re-add the custom files"],"exampleFix":"// before\n{\n  \"apps\": {\n    \"pki\": {\n      \"certificate_authorities\": {\n        \"local\": {\n          \"root\": { \"certificate\": \"/wrong/path/root.crt\", \"private_key\": \"/wrong/path/root.key\" }\n        }\n      }\n    }\n  }\n}\n\n// after: correct, process-readable paths\n{\n  \"apps\": {\n    \"pki\": {\n      \"certificate_authorities\": {\n        \"local\": {\n          \"root\": { \"certificate\": \"/etc/caddy/pki/root.crt\", \"private_key\": \"/etc/caddy/pki/root.key\" }\n        }\n      }\n    }\n  }\n}","handlingStrategy":"validation","validationCode":"// in CI: adapt and validate before deploy so provisioning errors never reach production\ncaddy adapt --config Caddyfile --adapter caddyfile > caddy.json\ncaddy validate --config caddy.json --adapter json\n# additionally check referenced files exist:\n#   for f in /etc/caddy/pki/root.crt /etc/caddy/pki/root.key; do test -r $f || exit 1; done","typeGuard":null,"tryCatchPattern":"// if embedding Caddy programmatically\nerr = caddy.Run(cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"provisioning CA\") {\n        // config/environment problem: inspect wrapped cause, fix CA files/paths\n    }\n    return err\n}","preventionTips":["Run caddy validate on every config change in CI, as the same user/context as production","Use absolute paths for cert/key files and lint for their existence in deploy scripts","Validate PEMs with openssl before referencing them (x509 -noout / pkey -noout must both succeed)","Pair every cert file with its key in versioned variables/secrets, never independently sourced"],"tags":["pki","configuration","startup","provisioning"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}