What causes "protocol name must be within '/p2p/' namespace" in ipfs/kubo?

Prefix the protocol with `/p2p/`, e.g. `ipfs p2p forward /p2p/myapp/1.0.0 /ip4/127.0.0.1/tcp/8080 `.

protocol name must be within '/p2p/' namespace

Error message

protocol name must be within '/p2p/' namespace

What it means

`ipfs p2p forward` (local forwarding) reserves the `/p2p/` protocol namespace for kubo's built-in p2p protocols. Unless the caller passes the `--allow-custom-protocol` option, the requested protocol ID must start with the P2PProtoPrefix (`/p2p/`); otherwise the command refuses before opening the listener.

Source

Thrown at core/commands/p2p.go:161

		listenOpt := req.Arguments[1]
		targetOpt := req.Arguments[2]

		proto := protocol.ID(protoOpt)

		listen, err := ma.NewMultiaddr(listenOpt)
		if err != nil {
			return err
		}

		targets, err := parseIpfsAddr(targetOpt)
		if err != nil {
			return err
		}

		allowCustom, _ := req.Options[allowCustomProtocolOptionName].(bool)

		if !allowCustom && !strings.HasPrefix(string(proto), P2PProtoPrefix) {
			return errors.New("protocol name must be within '" + P2PProtoPrefix + "' namespace")
		}

		listener, err := forwardLocal(n.Context(), n.P2P, n.Peerstore, proto, listen, targets)
		if err != nil {
			return err
		}

		foreground, _ := req.Options[foregroundOptionName].(bool)
		if foreground {
			if err := res.Emit(&P2PForegroundOutput{
				Status:   "active",
				Protocol: protoOpt,
				Address:  listenOpt,
			}); err != nil {
				return err
			}
			// Wait for either context cancellation (Ctrl+C/daemon shutdown)
			// or listener removal (ipfs p2p close)

View on GitHub (pinned to 329838acdf)

Solutions

Prefix the protocol with `/p2p/`, e.g. `ipfs p2p forward /p2p/myapp/1.0.0 /ip4/127.0.0.1/tcp/8080 <target>`.
If the custom namespace is intentional, add `--allow-custom-protocol` to the command.
Ensure the same protocol string is used on both ends (listen and dial) of the tunnel.

Example fix

// before
ipfs p2p forward myapp/1.0.0 /ip4/127.0.0.1/tcp/8080 <peerid>
// after
ipfs p2p forward /p2p/myapp/1.0.0 /ip4/127.0.0.1/tcp/8080 <peerid>   # or add --allow-custom-protocol

Defensive patterns

Strategy: validation

Validate before calling

const p2pPrefix = "/p2p/"
proto := "myapp/1.0.0"
if !strings.HasPrefix(proto, p2pPrefix) {
    proto = p2pPrefix + proto // or add --allow-custom-protocol
}

Prevention

Always name p2p tunnel protocols under /p2p/ unless you deliberately pass --allow-custom-protocol.
Share a single protocol-string constant between listen and dial sides.
Sanitize user-supplied protocol input to enforce the prefix.

When it happens

Trigger: Running `ipfs p2p forward <proto> <listen> <target>` where proto does not begin with `/p2p/` and `--allow-custom-protocol` (allowCustomProtocolOptionName) is not set, e.g. `ipfs p2p forward tcp/8080 ...`.

Common situations: Users porting plain TCP forwarding examples that use bare protocol names; forgetting the required `/p2p/` prefix such as `/x/custom` instead of `/p2p/x/custom` or omitting the flag when intentionally using a custom namespace.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/9eb84ee0825b73b4. Report an issue: GitHub.