{"record":{"id":"4d91bb2b77c5eb00","repo":"caddyserver/caddy","slug":"failed-to-load-network-proxy-module-v","errorCode":null,"errorMessage":"failed to load network_proxy module: %v","messagePattern":"failed to load network_proxy module: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/reverseproxy/httptransport.go","lineNumber":379,"sourceCode":"\t\t\t\twriteTimeout: time.Duration(h.WriteTimeout),\n\t\t\t\tlogger:       caddyCtx.Logger(),\n\t\t\t}\n\t\t}\n\n\t\treturn conn, nil\n\t}\n\n\t// negotiate any HTTP/SOCKS proxy for the HTTP transport\n\tproxy := http.ProxyFromEnvironment\n\tif h.ForwardProxyURL != \"\" {\n\t\tcaddyCtx.Logger().Warn(\"forward_proxy_url is deprecated; use network_proxy instead\")\n\t\tu := network.ProxyFromURL{URL: h.ForwardProxyURL}\n\t\th.NetworkProxyRaw = caddyconfig.JSONModuleObject(u, \"from\", \"url\", nil)\n\t}\n\tif len(h.NetworkProxyRaw) != 0 {\n\t\tproxyMod, err := caddyCtx.LoadModule(h, \"NetworkProxyRaw\")\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to load network_proxy module: %v\", err)\n\t\t}\n\t\tif m, ok := proxyMod.(caddy.ProxyFuncProducer); ok {\n\t\t\tproxy = m.ProxyFunc()\n\t\t} else {\n\t\t\treturn nil, fmt.Errorf(\"network_proxy module is not `(func(*http.Request) (*url.URL, error))``\")\n\t\t}\n\t}\n\t// we need to keep track if a proxy is used for a request\n\tproxyWrapper := func(req *http.Request) (*url.URL, error) {\n\t\tif proxy == nil {\n\t\t\treturn nil, nil\n\t\t}\n\t\tu, err := proxy(req)\n\t\tif u == nil || err != nil {\n\t\t\treturn u, err\n\t\t}\n\t\t// there must be a proxy for this request\n\t\tcaddyhttp.SetVar(req.Context(), proxyVarKey, u)","sourceCodeStart":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/reverseproxy/httptransport.go#L361-L397","documentation":"When a `network_proxy` module (or the deprecated `forward_proxy_url`, which is converted to one) is configured on the HTTP transport, Caddy loads it via `caddyCtx.LoadModule(h, \"NetworkProxyRaw\")`. Any error from module instantiation (unknown module ID, bad inline JSON, failed Provision) is wrapped with this message and transport creation fails.","triggerScenarios":"Setting `network_proxy` in JSON with a typo'd module name or invalid inline config; using forward_proxy_url whose auto-generated module object fails to load; a custom build missing the legacy import for the network_proxy module namespace.","commonSituations":"Custom Caddy binaries built without the `caddy.modules.logging`-style import for the http transport network proxy modules; version drift where module IDs were renamed; malformed JSON hand-edited configs.","solutions":["Read the wrapped error (%v) — it names the real cause such as unknown module or unmarshal failure","Fix the module name in network_proxy's \"from\"/protocol field to a registered module (e.g. from: \"url\")","If using a custom build, ensure the package providing the module is imported (modules/standard or your own imports)","Run `caddy list-modules` and confirm the network proxy module appears"],"exampleFix":"// JSON before\n\"network_proxy\": {\"from\": \"http\"}\n// JSON after\n\"network_proxy\": {\"from\": \"url\", \"url\": \"http://proxy.internal:3128\"}","handlingStrategy":"validation","validationCode":"// before deploy, confirm the module exists in this build\n// caddy list-modules | grep caddy.http.transport.proxy\nif !moduleRegistered(\"caddy.http.transport.proxy.url\") {\n\treturn errors.New(\"network_proxy module missing from build\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `caddy list-modules` after custom builds to verify proxy modules are compiled in","Use `caddy validate --config` in CI to catch module-load failures before deploy"],"tags":["reverse-proxy","http-transport","modules","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}