{"record":{"id":"3f2b3aa0e897d5fc","repo":"caddyserver/caddy","slug":"loading-new-config-v","errorCode":null,"errorMessage":"loading new config: %v","messagePattern":"loading new config: (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"caddy.go","lineNumber":264,"sourceCode":"\t// our old representation of caddy's actual config\n\terr = unsyncedDecodeAndRun(newCfg, true)\n\tif err != nil {\n\t\tif len(rawCfgJSON) > 0 {\n\t\t\t// restore old config state to keep it consistent\n\t\t\t// with what caddy is still running; we need to\n\t\t\t// unmarshal it again because it's likely that\n\t\t\t// pointers deep in our rawCfg map were modified\n\t\t\tvar oldCfg any\n\t\t\terr2 := json.Unmarshal(rawCfgJSON, &oldCfg)\n\t\t\tif err2 != nil {\n\t\t\t\terr = fmt.Errorf(\"%v; additionally, restoring old config: %v\", err, err2)\n\t\t\t}\n\t\t\trawCfg[rawConfigKey] = oldCfg\n\t\t} else {\n\t\t\trawCfg[rawConfigKey] = nil\n\t\t}\n\n\t\treturn fmt.Errorf(\"loading new config: %v\", err)\n\t}\n\n\t// success, so update our stored copy of the encoded\n\t// config to keep it consistent with what caddy is now\n\t// running (storing an encoded copy is not strictly\n\t// necessary, but avoids an extra json.Marshal for\n\t// each config change)\n\trawCfgJSON = newCfg\n\trawCfgIndex = idx\n\n\treturn nil\n}\n\n// readConfig traverses the current config to path\n// and writes its JSON encoding to out.\nfunc readConfig(path string, out io.Writer) error {\n\trawCfgMu.RLock()\n\tdefer rawCfgMu.RUnlock()","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/caddy.go#L246-L282","documentation":"The new config was accepted by changeConfig but unsyncedDecodeAndRun failed while preparing or running it — module loading, provisioning, validation, or app startup returned an error. Caddy restores the previous raw config and returns 'loading new config' wrapping the root cause. The old config keeps running, making admin-API loads atomic.","triggerScenarios":"POST /load (or PUT/PATCH /config/) with a config that references an unregistered module ID, fails Validate(), binds a port already in use, has invalid TLS/automation policies, or whose app Start() errors. Caddyfile users see the equivalent from 'caddy validate' failures.","commonSituations":"Deploying a config that uses a module not compiled into the custom build; port conflicts on reload; invalid ACME/TLS settings; schema changes between Caddy versions (renamed fields produce provisioning errors).","solutions":["Read the wrapped error — it identifies the failing module, field, or listener precisely.","Pre-validate before applying: caddy validate --config <file> (add --adapter if not JSON).","Fix the named module/field (correct module ID, free the port, fix TLS settings) and retry the load.","For custom builds, ensure the required plugin is compiled in (caddy list-modules | grep <name>)."],"exampleFix":"# before\ncurl -X POST localhost:2019/load -H 'Content-Type: application/json' --data @broken.json\n\n# after: validate first, then load\ncaddy validate --config caddy.json && curl -X POST localhost:2019/load -H 'Content-Type: application/json' --data @caddy.json","handlingStrategy":"try-catch","validationCode":"// Dry-run the exact bytes you will POST.\nif err := caddy.Validate(cfgBytes); err != nil { // or: caddy validate --config file\n    return err\n}","typeGuard":null,"tryCatchPattern":"resp, err := client.Post(\"http://localhost:2019/load\", \"application/json\", bytes.NewReader(cfg))\nif err == nil && resp.StatusCode >= 400 {\n    body, _ := io.ReadAll(resp.Body)\n    if strings.Contains(string(body), \"loading new config\") {\n        // old config still running; fix the named module/field and retry\n    }\n}","preventionTips":["Run caddy validate --config in CI for every config change.","Pin plugin versions and rebuild with xcaddy to keep module IDs available.","Check port availability before deploying configs that bind new listeners."],"tags":["caddy","admin-api","config","provisioning","reload"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}