ipfs/kubo · error

cannot read migration: %w

Error message

cannot read migration: %w

What it means

After asserting the fetched node is a file, ipfsGet streams it to io.Discard purely to verify it can be read end-to-end. Any read error while consuming the file is wrapped as this error, meaning the migration artifact is unreadable or truncated.

Source

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

	}

	return nil
}

func ipfsGet(ctx context.Context, ufs coreiface.UnixfsAPI, ipfsPath path.Path) error {
	nd, err := ufs.Get(ctx, ipfsPath)
	if err != nil {
		return err
	}
	defer nd.Close()

	fnd, ok := nd.(files.File)
	if !ok {
		return fmt.Errorf("not a file node: %q", ipfsPath)
	}
	_, err = io.Copy(io.Discard, fnd)
	if err != nil {
		return fmt.Errorf("cannot read migration: %w", err)
	}
	fmt.Printf("Added migration file: %q\n", ipfsPath)
	return nil
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-run `ipfs daemon --migrate` to re-download the migration artifact cleanly
2. Check the temp node's logs for datastore/bitswap errors during the read
3. Verify the artifact's checksum against the dist.ipfs.tech release; re-fetch if mismatched
4. Check disk health/space on the temp node's IPFS_PATH
5. Use the external fs-repo-migrations binary as a fallback

When it happens

Trigger: io.Copy(io.Discard, fnd) returns an error while reading the migration file from the temp node — e.g. the block data is missing (context deadline), the node's datastore is corrupt, or the underlying RPC/stream breaks mid-read.

Common situations: Truncated or corrupted migration binary in the temp node's store; temp node shut down mid-read; bitswap timeout fetching blocks the temp node doesn't actually have.

Related errors

• abort failed: close: %w, remove: %v
• e (stream error trailer header value)
• cannot get migrations from unknown fetcher type
• nothing downloaded by ipfs fetcher
• no local swarm address for migration node

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