caddyserver/caddy · error

module %s (%T) is not an IP range source

Error message

module %s (%T) is not an IP range source

What it means

The 'trusted_proxies <module> ...' server option unmarshals a module from 'http.ip_sources.' (e.g. static, cloudflare) and asserts it implements caddyhttp.IPRangeSource. Note that a misspelled or missing module name fails earlier inside caddyfile.UnmarshalModule; this specific error fires only when the module unmarshals fine but does not implement the IP range source interface — i.e. a broken or incompatible plugin in that namespace.

Source

Thrown at caddyconfig/httpcaddyfile/serveroptions.go:279

			}
			boolVal := true
			if d.Val() == "insecure_off" {
				boolVal = false
			}
			serverOpts.StrictSNIHost = &boolVal

		case "trusted_proxies":
			if !d.NextArg() {
				return nil, d.Err("trusted_proxies expects an IP range source module name as its first argument")
			}
			modID := "http.ip_sources." + d.Val()
			unm, err := caddyfile.UnmarshalModule(d, modID)
			if err != nil {
				return nil, err
			}
			source, ok := unm.(caddyhttp.IPRangeSource)
			if !ok {
				return nil, fmt.Errorf("module %s (%T) is not an IP range source", modID, unm)
			}
			jsonSource := caddyconfig.JSONModuleObject(
				source,
				"source",
				source.(caddy.Module).CaddyModule().ID.Name(),
				nil,
			)
			serverOpts.TrustedProxiesRaw = jsonSource

		case "trusted_proxies_strict":
			if d.NextArg() {
				return nil, d.ArgErr()
			}
			serverOpts.TrustedProxiesStrict = 1

		case "trusted_proxies_unix":
			if d.NextArg() {
				return nil, d.ArgErr()

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check which modules are registered: 'caddy list-modules | grep http.ip_sources' and use a documented one (static, cloudflare).
2. Rebuild the plugin against your Caddy version.
3. If developing the module, implement caddyhttp.IPRangeSource (GetIPRanges) and add a compile-time guard.

Example fix

# use a valid, documented IP range source
servers {
  trusted_proxies static 10.0.0.0/8 172.16.0.0/12
}

caddy list-modules | grep '^http.ip_sources.'  # e.g. static, cloudflare

var _ caddyhttp.IPRangeSource = (*StaticRanges)(nil)

When it happens

Trigger: A plugin registering a module under http.ip_sources that does not implement GetIPRanges; a custom IP source module compiled against an older Caddy where the interface differed.

Common situations: Developing a custom trusted-proxy IP source and forgetting the interface; version skew between a third-party ip_sources plugin and Caddy core.

Related errors

• matcher module '%s' is not a Caddyfile unmarshaler
• matcher module '%s' is not a request matcher
• marshaling matcher set %#v: %v
• module %s (%T) is not a listener wrapper
• module %s (%T) is not a packet conn wrapper

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/c3ff18e1700fbe58. Report an issue: GitHub.