{"record":{"id":"27a14b2f1b274ce4","repo":"caddyserver/caddy","slug":"loading-trusted-proxies-modules-v","errorCode":null,"errorMessage":"loading trusted proxies modules: %v","messagePattern":"loading trusted proxies modules: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/app.go","lineNumber":295,"sourceCode":"\t\t// otherwise be exploited by sending an unprotected SNI\n\t\t// value during a TLS handshake, then putting a protected\n\t\t// domain in the Host header after establishing connection;\n\t\t// this is a safe default, but we allow users to override\n\t\t// it for example in the case of running a proxy where\n\t\t// domain fronting is desired and access is not restricted\n\t\t// based on hostname\n\t\tif srv.StrictSNIHost == nil && srv.hasTLSClientAuth() {\n\t\t\tapp.logger.Warn(\"enabling strict SNI-Host enforcement because TLS client auth is configured\",\n\t\t\t\tzap.String(\"server_id\", srvName))\n\t\t\ttrueBool := true\n\t\t\tsrv.StrictSNIHost = &trueBool\n\t\t}\n\n\t\t// set up the trusted proxies source\n\t\tfor srv.TrustedProxiesRaw != nil {\n\t\t\tval, err := ctx.LoadModule(srv, \"TrustedProxiesRaw\")\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"loading trusted proxies modules: %v\", err)\n\t\t\t}\n\t\t\tsrv.trustedProxies = val.(IPRangeSource)\n\t\t}\n\n\t\t// set the default client IP header to read from\n\t\tif srv.ClientIPHeaders == nil {\n\t\t\tsrv.ClientIPHeaders = []string{\"X-Forwarded-For\"}\n\t\t}\n\n\t\t// precompute underscore and dot header allowlist rules\n\t\tif err := srv.provisionUnderscoreHeaders(); err != nil {\n\t\t\treturn fmt.Errorf(\"server %s: %v\", srvName, err)\n\t\t}\n\t\tif err := srv.provisionDotHeaders(); err != nil {\n\t\t\treturn fmt.Errorf(\"server %s: %v\", srvName, err)\n\t\t}\n\n\t\t// process each listener address","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/app.go#L277-L313","documentation":"During http app provisioning, each server's trusted_proxies source module (TrustedProxiesRaw, an IPRangeSource such as static_ranges or a trusted_proxies plugin) is loaded via ctx.LoadModule; failures in resolving the module or its inline config (e.g. malformed CIDR ranges) are wrapped with this message.","triggerScenarios":"trusted_proxies static_ranges <ranges> where a range is not a valid CIDR/IP range; a third-party IP range source module not compiled into the binary; JSON with a misspelled module name under trusted_proxies.","commonSituations":"Copying Docker/Kubernetes CIDR lists with typos or bare IPs where ranges are expected; plugin missing from xcaddy builds; cloud environments where the proxy CIDR list changed and was hand-patched incorrectly.","solutions":["Read the wrapped error — invalid CIDR text names the bad range; 'module not registered' names a missing module.","Use valid CIDRs (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fd00::/8) or single IPs where supported by the module.","Rebuild with the plugin if a custom IPRangeSource is intended.","Validate with 'caddy validate' after edits."],"exampleFix":"// before (caddyfile)\nsrv0 {\n    trusted_proxies static_ranges 172.17.0.0/8 10.0.0.0/8  # 172.17 is inside /12, wrong mask style\n}\n\n// after\nsrv0 {\n    trusted_proxies static_ranges 172.16.0.0/12 10.0.0.0/8\n}","handlingStrategy":"validation","validationCode":"// validate CIDR entries before load\nfunc cidrsOK(ranges []string) error {\n    for _, r := range ranges {\n        if _, _, err := net.ParseCIDR(r); err != nil {\n            if net.ParseIP(r) == nil {\n                return fmt.Errorf(\"bad trusted proxy range %q: %w\", r, err)\n            }\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := caddy.Validate(cfg); err != nil {\n    if strings.Contains(err.Error(), \"loading trusted proxies modules\") {\n        // nested cause names the bad range or missing module — fix and re-validate\n    }\n    return err\n}","preventionTips":["Source proxy CIDR lists programmatically (cloud metadata) instead of hand-editing.","Validate CIDRs with net.ParseCIDR in any config-generation tooling.","Confirm the IPRangeSource module is compiled in when using third-party sources."],"tags":["http","trusted-proxies","module-system","validation"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}