{"record":{"id":"35ea52168d5ad5ce","repo":"caddyserver/caddy","slug":"failed-to-load-network-proxy-module-v-35ea52","errorCode":null,"errorMessage":"failed to load network_proxy module: %v","messagePattern":"failed to load network_proxy module: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/acmeissuer.go","lineNumber":271,"sourceCode":"\nfunc (iss *ACMEIssuer) makeIssuerTemplate(ctx caddy.Context) (certmagic.ACMEIssuer, error) {\n\ttemplate := certmagic.ACMEIssuer{\n\t\tCA:                iss.CA,\n\t\tTestCA:            iss.TestCA,\n\t\tEmail:             iss.Email,\n\t\tProfile:           iss.Profile,\n\t\tAccountKeyPEM:     iss.AccountKey,\n\t\tCertObtainTimeout: time.Duration(iss.ACMETimeout),\n\t\tTrustedRoots:      iss.rootPool,\n\t\tExternalAccount:   iss.ExternalAccount,\n\t\tNotAfter:          time.Duration(iss.CertificateLifetime),\n\t\tLogger:            iss.logger,\n\t}\n\n\tif len(iss.NetworkProxyRaw) != 0 {\n\t\tproxyMod, err := ctx.LoadModule(iss, \"NetworkProxyRaw\")\n\t\tif err != nil {\n\t\t\treturn template, 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\ttemplate.HTTPProxy = m.ProxyFunc()\n\t\t} else {\n\t\t\treturn template, fmt.Errorf(\"network_proxy module is not `(func(*http.Request) (*url.URL, error))``\")\n\t\t}\n\t}\n\n\tif iss.Challenges != nil {\n\t\tif iss.Challenges.HTTP != nil {\n\t\t\ttemplate.DisableHTTPChallenge = iss.Challenges.HTTP.Disabled\n\t\t\ttemplate.AltHTTPPort = iss.Challenges.HTTP.AlternatePort\n\t\t}\n\t\tif iss.Challenges.TLSALPN != nil {\n\t\t\ttemplate.DisableTLSALPNChallenge = iss.Challenges.TLSALPN.Disabled\n\t\t\ttemplate.AltTLSALPNPort = iss.Challenges.TLSALPN.AlternatePort\n\t\t}\n\t\tif iss.Challenges.DNS != nil {","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/acmeissuer.go#L253-L289","documentation":"Returned while building the ACME issuer template (modules/caddytls/acmeissuer.go:271) when ctx.LoadModule fails to load the configured network proxy module for the issuer (network_proxy directive, JSON \"network_proxy_raw\"). Wrapped causes: the proxy module name is not registered in this build, or the module's own provisioning failed (bad proxy URL, unsupported scheme).","triggerScenarios":"Configuring an ACME issuer with network_proxy <module> where the module is a third-party plugin (e.g. forwarded_connect or custom HTTP connect proxies) not compiled into the binary, or where the module's options (address, scheme) are invalid so its Provision errors.","commonSituations":"Routing ACME traffic through a corporate proxy on air-gapped networks; configs migrated from an xcaddy build to the stock binary; plugin renamed or its option schema changed between versions; typo in the module name.","solutions":["Check caddy list-modules for the network proxy module; if absent, build with xcaddy and the plugin's --with flag","Read the wrapped error for the module's own provisioning failure and fix its options (valid URL, supported scheme)","Correct the module name spelling to match its registered ID","If direct egress works, remove the network_proxy directive"],"exampleFix":"# before\n example.com {\n   tls {\n     issuer acme {\n       network_proxy connect {\n         address proxy.internal:3128\n       }\n     }\n   }\n }\n\n# after: build with the proxy plugin first\nxcaddy build --with github.com/mholt/caddy-network-proxy-connect\n# keep config; verify module present:\ncaddy list-modules | grep network_proxy","handlingStrategy":"validation","validationCode":"# before deploying a config with network_proxy, assert the module is built in\ncaddy list-modules | grep -q 'network_proxy' || {\n  echo \"network_proxy module missing; rebuild: xcaddy build --with <plugin>\"; exit 1; }","typeGuard":null,"tryCatchPattern":"if err := issuer.Provision(ctx); err != nil {\n    if strings.Contains(err.Error(), \"failed to load network_proxy module\") {\n        // missing plugin (rebuild binary) or invalid proxy options (fix address/scheme)\n    }\n    return err\n}","preventionTips":["Treat network_proxy plugins as part of the build artifact: document xcaddy flags beside the config","Assert module presence with caddy list-modules in CI post-build","Validate proxy URLs (scheme://host:port) before config submit","Re-test ACME reachability through the proxy after any proxy-side changes"],"tags":["tls","acme","network-proxy","plugin","xcaddy"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}