{"record":{"id":"daf6e85b47c3403c","repo":"caddyserver/caddy","slug":"s-invalid-configuration-v","errorCode":null,"errorMessage":"%s: invalid configuration: %v","messagePattern":"(.+?): invalid configuration: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"context.go","lineNumber":450,"sourceCode":"\t\t\t\tif err2 != nil {\n\t\t\t\t\terr = fmt.Errorf(\"%v; additionally, cleanup: %v\", err, err2)\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"provision %s: %v\", modInfo, err)\n\t\t}\n\t}\n\n\tif validator, ok := val.(Validator); ok {\n\t\terr = validator.Validate()\n\t\tif err != nil {\n\t\t\t// since the module was already provisioned, make sure we clean up\n\t\t\tif cleanerUpper, ok := val.(CleanerUpper); ok {\n\t\t\t\terr2 := cleanerUpper.Cleanup()\n\t\t\t\tif err2 != nil {\n\t\t\t\t\terr = fmt.Errorf(\"%v; additionally, cleanup: %v\", err, err2)\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"%s: invalid configuration: %v\", modInfo, err)\n\t\t}\n\t}\n\n\tctx.moduleInstances[id] = append(ctx.moduleInstances[id], val)\n\n\t// if the loaded module happens to be an app that can emit events, store it so the\n\t// core can have access to emit events without an import cycle\n\tif ee, ok := val.(eventEmitter); ok {\n\t\tif _, ok := ee.(App); ok {\n\t\t\tctx.cfg.eventEmitter = ee\n\t\t}\n\t}\n\n\treturn val, nil\n}\n\n// loadModuleInline loads a module from a JSON raw message which decodes to\n// a map[string]any, where one of the object keys is moduleNameKey","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/context.go#L432-L468","documentation":"After a module is provisioned, LoadModuleByID calls Validate() on Validator implementations to check semantic correctness. Any error is wrapped as '%s: invalid configuration: %v' where %s identifies the module (its caddy.ModuleInfo string). This is the standard error users see when config is syntactically valid JSON but semantically wrong for the module.","triggerScenarios":"A module's Validate() returns an error: contradictory options, empty required collections, out-of-range values, invalid combinations that cannot be expressed as struct tags — e.g. an upstream with no dial addresses, a TLS policy with conflicting client auth settings.","commonSituations":"Reverse proxy blocks with zero upstreams; matchers with empty patterns; ACME configs combining incompatible options; version changes tightening validation rules so previously-accepted configs now fail after upgrade.","solutions":["Read the inner error after 'invalid configuration:' — module validators are written to be descriptive","Adjust the named module's options to satisfy the stated constraint","If upgrading Caddy revealed this, check the changelog/release notes for the module's new validation rules and migrate the config","Run `caddy validate --config <file> [--adapter <adapter>]` in CI to catch these before deploy"],"exampleFix":"// before\n{ \"handler\": \"reverse_proxy\", \"upstreams\": [] }\n// after\n{ \"handler\": \"reverse_proxy\", \"upstreams\": [ { \"dial\": \"127.0.0.1:8080\" } ] }","handlingStrategy":"validation","validationCode":"// Validate the full config before running — surfaces module Validate() failures cleanly\nif err := caddy.ValidateWithAdapter(cfgJSON, caddyfile.Adapter{}); err != nil { // or use CLI\n    return err\n}","typeGuard":null,"tryCatchPattern":"if _, err := ctx.LoadModuleByID(id, raw); err != nil {\n    if strings.Contains(err.Error(), \"invalid configuration\") {\n        // semantic config error: fix options, not code\n    }\n    return err\n}","preventionTips":["Run `caddy validate` on every config change","Read module docs for semantic constraints (non-empty lists, mutually exclusive options)","After upgrading Caddy, re-validate existing configs for tightened validators"],"tags":["caddy","module-system","validation","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}