caddyserver/caddy · error

module %s (%T) is not a packet conn wrapper

Error message

module %s (%T) is not a packet conn wrapper

What it means

Same pattern as listener_wrappers but for 'packet_conn_wrappers' in the servers block: the module under 'caddy.packetconns.' must implement caddy.PacketConnWrapper (wrap a net.PacketConn, e.g. for QUIC/HTTP-3 UDP sockets). The type assertion failing means the resolved module is not a packet-conn wrapper.

Source

Thrown at caddyconfig/httpcaddyfile/serveroptions.go:117

				jsonListenerWrapper := caddyconfig.JSONModuleObject(
					listenerWrapper,
					"wrapper",
					listenerWrapper.(caddy.Module).CaddyModule().ID.Name(),
					nil,
				)
				serverOpts.ListenerWrappersRaw = append(serverOpts.ListenerWrappersRaw, jsonListenerWrapper)
			}

		case "packet_conn_wrappers":
			for nesting := d.Nesting(); d.NextBlock(nesting); {
				modID := "caddy.packetconns." + d.Val()
				unm, err := caddyfile.UnmarshalModule(d, modID)
				if err != nil {
					return nil, err
				}
				packetConnWrapper, ok := unm.(caddy.PacketConnWrapper)
				if !ok {
					return nil, fmt.Errorf("module %s (%T) is not a packet conn wrapper", modID, unm)
				}
				jsonPacketConnWrapper := caddyconfig.JSONModuleObject(
					packetConnWrapper,
					"wrapper",
					packetConnWrapper.(caddy.Module).CaddyModule().ID.Name(),
					nil,
				)
				serverOpts.PacketConnWrappersRaw = append(serverOpts.PacketConnWrappersRaw, jsonPacketConnWrapper)
			}

		case "timeouts":
			for nesting := d.Nesting(); d.NextBlock(nesting); {
				switch d.Val() {
				case "read_body":
					if !d.NextArg() {
						return nil, d.ArgErr()
					}
					dur, err := caddy.ParseDuration(d.Val())

View on GitHub (pinned to 50e54ee279)

Solutions

1. Verify the module is listed under 'caddy.packetconns.' via 'caddy list-modules'.
2. Move listener-only modules back to listener_wrappers if they were misplaced.
3. Rebuild the plugin against your Caddy version.
4. If developing the plugin, implement WrapPacketConn plus a compile-time guard.

caddy list-modules | grep '^caddy.packetconns.'  # confirm the module exists

var _ caddy.PacketConnWrapper = (*MyWrapper)(nil)

When it happens

Trigger: Using a listener-wrapper-only module in packet_conn_wrappers; a plugin registered under caddy.packetconns that lacks WrapPacketConn; version skew between core and plugin after upgrade.

Common situations: Configuring QUIC/UDP-related wrappers without the right build; plugin API changes across minor Caddy releases.

Related errors

• module %s (%T) is not a listener wrapper
• 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 an IP range source

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