ipfs/kubo · error

could not connect to migration peer %q: %s

Error message

could not connect to migration peer %q: %s

What it means

After building a CoreAPI for the node, addMigrationPaths connects the main node's swarm to the temporary migration peer before pulling migration files. This error wraps whatever failure ipfs.Swarm().Connect returned, identifying the peer by ID.

Source

Thrown at cmd/ipfs/kubo/add_migrations.go:118

// addMigrationPaths adds the files at paths to IPFS, optionally pinning
// them. This is done after connecting to the peer.
func addMigrationPaths(ctx context.Context, node *core.IpfsNode, peerInfo peer.AddrInfo, paths []path.Path, pin bool) error {
	if len(paths) == 0 {
		return errors.New("nothing downloaded by ipfs fetcher")
	}
	if len(peerInfo.Addrs) == 0 {
		return errors.New("no local swarm address for migration node")
	}

	ipfs, err := coreapi.NewCoreAPI(node)
	if err != nil {
		return err
	}

	// Connect to temp node
	if err := ipfs.Swarm().Connect(ctx, peerInfo); err != nil {
		return fmt.Errorf("could not connect to migration peer %q: %s", peerInfo.ID, err)
	}
	fmt.Printf("connected to migration peer %q\n", peerInfo)

	if pin {
		pinAPI := ipfs.Pin()
		for _, ipfsPath := range paths {
			err := pinAPI.Add(ctx, ipfsPath)
			if err != nil {
				return err
			}
			fmt.Printf("Added and pinned migration file: %q\n", ipfsPath)
		}
		return nil
	}

	ufs := ipfs.Unixfs()

	// Add migration files

View on GitHub (pinned to 329838acdf)

Solutions

1. Read the wrapped %s cause: fix the underlying dial error (wrong address, connection refused, timeout)
2. Confirm the temp migration node is still running and its swarm address is correct
3. Retry the daemon with --migrate; transient dials often succeed on a second run
4. Bypass the networked path entirely: run `ipfs repo migrate` / fs-repo-migrations out-of-band

if err := daemonCmd.Run(); err != nil {
    if strings.Contains(err.Error(), "could not connect to migration peer") {
        // retry with --migrate after confirming temp node is alive
    }
}

When it happens

Trigger: ipfs.Swarm().Connect(ctx, peerInfo) fails — temp node unreachable at the given addresses, transport mismatch, or handshake failure — while running daemon-triggered repo migrations.

Common situations: Temp node exited before connect; NAT/firewall rules on loopback; libp2p security/transport incompatibility between the old and new binary; dial timeouts under load.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• no local swarm address for migration node
• could not find a non dev version
• cannot get migrations from unknown fetcher type
• nothing downloaded by ipfs fetcher
• not a file node: %q

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