ipfs/kubo · error

failed to parse peer address '%s': %s

Error message

failed to parse peer address '%s': %s

What it means

The `ipfs ping` command wraps its argument with this message when `ParsePeerParam` cannot interpret it as a valid peer address or peer ID. The command accepts either a bare peer ID (CIDv1 base32 or base58 multihash) or a multiaddr that includes the `/p2p/<peerID>` component; anything else is rejected before any network activity. The wrapped underlying error names the exact parse failure.

Source

Thrown at core/commands/ping.go:63

		cmds.StringArg("peer ID", true, true, "ID of peer to be pinged.").EnableStdin(),
	},
	Options: []cmds.Option{
		cmds.IntOption(pingCountOptionName, "n", "Number of ping messages to send.").WithDefault(10),
	},
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		n, err := cmdenv.GetNode(env)
		if err != nil {
			return err
		}

		// Must be online!
		if !n.IsOnline {
			return ErrNotOnline
		}

		addr, pid, err := ParsePeerParam(req.Arguments[0])
		if err != nil {
			return fmt.Errorf("failed to parse peer address '%s': %s", req.Arguments[0], err)
		}

		if pid == n.Identity {
			return ErrPingSelf
		}

		if addr != nil {
			n.Peerstore.AddAddr(pid, addr, pstore.TempAddrTTL) // temporary
		}

		numPings, _ := req.Options[pingCountOptionName].(int)
		if numPings <= 0 {
			return fmt.Errorf("ping count must be greater than 0, was %d", numPings)
		}

		if len(n.Peerstore.Addrs(pid)) == 0 {
			// Make sure we can find the node in question
			if err := res.Emit(&PingResult{

View on GitHub (pinned to 329838acdf)

Solutions

1. Verify the argument is either a valid peer ID (e.g. from `ipfs id` or `ipfs swarm peers` output) or a full multiaddr ending in `/p2p/<peerID>`.
2. If passing a multiaddr, append the `/p2p/<peerID>` component; `ipfs ping /ip4/1.2.3.4/tcp/4001/p2p/Qm...` is valid, `/ip4/1.2.3.4/tcp/4001` alone is not.
3. Convert a CIDv0 peer ID if needed: peer IDs in base58btc (starting Qm or 12D3...) are accepted; check for stray whitespace or quoting with `echo -n "$ARG" | xxd`.
4. In code, validate with the same library before calling: `peer.Decode(id)` for bare IDs or `peer.AddrInfoFromString(s)` for multiaddrs.

Example fix

// before
ipfs ping /ip4/147.75.83.83/tcp/4001
// error: failed to parse peer address '/ip4/147.75.83.83/tcp/4001': ...

// after
ipfs ping /ip4/147.75.83.83/tcp/4001/p2p/QmSoLP4uB...
// or just the peer ID:
ipfs ping QmSoLP4uB...

import (
	"github.com/ipfs/boxo/peer"
)

func validPeerArg(s string) bool {
	_, _, err := peer.AddrInfoFromString(s)
	return err == nil
}

// before calling: ipfs ping <arg>
if !validPeerArg(arg) {
	// surface a clear message before invoking the CLI
}

func isPeerIDOrAddrInfo(s string) bool {
	if _, err := peer.Decode(s); err == nil {
		return true // bare peer ID
	}
	_, err := peer.AddrInfoFromString(s)
	return err == nil // multiaddr with /p2p/<id>
}

pid, err := peer.Decode(arg)
if err != nil {
	ai, aerr := peer.AddrInfoFromString(arg)
	if aerr != nil {
		return fmt.Errorf("not a peer ID or multiaddr-with-peerID: %q: %w", arg, aerr)
	}
	pid = ai.ID
}

When it happens

Trigger: Running `ipfs ping` with an argument that is not a valid multiaddr with a /p2p/ component and not a parseable peer ID: a CIDv0 peer ID in an unsupported encoding, a truncated ID, an IPFS path (/ipfs/...), a multiaddr missing the peer-ID component (e.g. `/ip4/1.2.3.4/tcp/4001` with no /p2p/ part), or a malformed CID.

Common situations: Pasting a full gateway URL or a CID instead of a peer ID; passing a multiaddr copied from `ipfs id` after stripping the `/p2p/Qm...` suffix; scripts using old `/ipfs/<id>` address syntax; shell quoting mangling the argument.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• unsupported API address: %s
• invalid bootstrap address: %s
• bootstrap address without a transport: %s
• failed to unmarshal json. %s
• invalid CID %q: %w

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