{"record":{"id":"dd463c97723ecd95","repo":"caddyserver/caddy","slug":"loading-initial-config-v","errorCode":null,"errorMessage":"loading initial config: %v","messagePattern":"loading initial config: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/commandfuncs.go","lineNumber":286,"sourceCode":"\n\t// If we have a source config file (we're running via 'caddy run --config ...'),\n\t// record it so SIGUSR1 can reload from the same file. Also provide a callback\n\t// that knows how to load/adapt that source when requested by the main process.\n\tif configFile != \"\" {\n\t\tcaddy.SetLastConfig(configFile, adapterUsed, func(file, adapter string) error {\n\t\t\tcfg, _, _, err := LoadConfig(file, adapter)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\treturn caddy.Load(cfg, true)\n\t\t})\n\t}\n\n\t// run the initial config\n\terr = caddy.Load(config, true)\n\tif err != nil {\n\t\tlogBuffer.FlushTo(defaultLogger)\n\t\treturn caddy.ExitCodeFailedStartup, fmt.Errorf(\"loading initial config: %v\", err)\n\t}\n\t// release the reference to the config so it can be GC'd\n\tconfig = nil //nolint:ineffassign,wastedassign\n\n\t// at this stage the config will have replaced the\n\t// default logger to the configured one, so we can\n\t// log normally, now that the config is running.\n\t// also clear our ref to the buffer so it can get GC'd\n\tlogger = caddy.Log()\n\tdefaultLogger = nil //nolint:ineffassign,wastedassign\n\tlogBuffer = nil     //nolint:wastedassign,ineffassign\n\tlogger.Info(\"serving initial configuration\")\n\n\t// if we are to report to another process the successful start\n\t// of the server, do so now by echoing back contents of stdin\n\tif pingbackFlag != \"\" {\n\t\tconfirmationBytes, err := io.ReadAll(os.Stdin)\n\t\tif err != nil {","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/cmd/commandfuncs.go#L268-L304","documentation":"Returned by `caddy run` when the initial caddy.Load(config, true) fails during startup. Before returning, the buffered early logs are flushed to the default logger so the actual provisioning/validation failure is visible. This is the top-level 'your config could not start' error; the root cause is in the flushed log lines immediately above it.","triggerScenarios":"Invalid JSON or Caddyfile syntax; unknown module IDs (plugin not compiled in); module Provision/Validate failures (bad listener addresses, invalid TLS automation, malformed matchers); port conflicts surface here too when servers bind.","commonSituations":"First run of a hand-edited config; upgrading Caddy major versions where config schema changed; custom builds missing standard modules; config referencing environment placeholders that resolved to empty values.","solutions":["Read the log lines flushed just before this error — they contain the module-level cause","Run caddy validate --config <file> --adapter <name> for a precise diagnostic","If a module is unknown, rebuild with xcaddy --with <module> or use the full distribution","Free conflicting ports or change listen addresses"],"exampleFix":"# before\n$ caddy run --config Caddyfile  # Error: loading initial config: loading config: ... unknown module\n# after\n$ xcaddy build --with github.com/caddy-dns/cloudflare\n$ caddy run --config Caddyfile","handlingStrategy":"validation","validationCode":"// validate the exact config before `caddy run`\nif out, err := exec.Command(\"caddy\", \"validate\", \"--config\", cfgPath, \"--adapter\", adapter).CombinedOutput(); err != nil {\n    return fmt.Errorf(\"refusing to run invalid config: %s\", out)\n}","typeGuard":null,"tryCatchPattern":"// in systemd unit: ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile\n// failures land in journalctl; alert on unit enter-failed state","preventionTips":["Gate every deploy on caddy validate in CI","After upgrades, re-validate: module IDs and schema can change between versions","Watch the flushed early logs above the error — they name the failing module"],"tags":["cli","caddy-run","config","startup","validation"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}