ipfs/kubo · error

IPFS downloads are not supported for legacy migrations (repo

Error message

IPFS downloads are not supported for legacy migrations (repo versions <16). Please use only HTTPS in Migration.DownloadSources

What it means

GetMigrationFetcher for legacy migrations (repo versions below 16) only supports plain HTTPS/HTTP fetchers; "IPFS" is explicitly rejected as a Migration.DownloadSources entry because legacy migration binaries cannot fetch over IPFS.

Source

Thrown at repo/fsrepo/migrations/migrations.go:181

//
// Deprecated: This function is used by legacy migration downloads and will be removed
// in a future version. Use RunHybridMigrations or RunEmbeddedMigrations instead.
func GetMigrationFetcher(downloadSources []string, distPath string, newIpfsFetcher func(string) Fetcher) (Fetcher, error) {
	const httpUserAgent = "kubo/migration"

	var fetchers []Fetcher
	for _, src := range downloadSources {
		src := strings.TrimSpace(src)
		switch src {
		case "HTTPS", "https", "HTTP", "http":
			// Expand the alias into the full ordered list of trustless
			// community-provided gateways so migration survives a
			// single-gateway outage.
			for _, gw := range defaultMigrationGateways {
				fetchers = append(fetchers, NewHttpFetcher(distPath, gw, httpUserAgent, 0))
			}
		case "IPFS", "ipfs":
			return nil, errors.New("IPFS downloads are not supported for legacy migrations (repo versions <16). Please use only HTTPS in Migration.DownloadSources")
		case "":
			// Ignore empty string
		default:
			u, err := url.Parse(src)
			if err != nil {
				return nil, fmt.Errorf("bad gateway address: %w", err)
			}
			switch u.Scheme {
			case "":
				u.Scheme = "https"
			case "https", "http":
			default:
				return nil, errors.New("bad gateway address: url scheme must be http or https")
			}
			fetchers = append(fetchers, NewHttpFetcher(distPath, u.String(), httpUserAgent, 0))
		}
	}

View on GitHub (pinned to 329838acdf)

Solutions

1. Remove "IPFS" from Migration.DownloadSources, keeping only HTTPS entries.
2. Run `ipfs config --json Migration.DownloadSources '["HTTPS"]'`.
3. If IPFS-based fetching is required, first upgrade the repo through supported HTTPS migrations.

Example fix

// before
ipfs config --json Migration.DownloadSources '["IPFS","HTTPS"]'
// after
ipfs config --json Migration.DownloadSources '["HTTPS"]'

for _, src := range cfg.Migration.DownloadSources {
    if strings.EqualFold(src, "IPFS") {
        return errors.New("IPFS source unsupported for repo versions <16")
    }
}

fetcher, err := cmd.GetMigrationFetcher(...)
if err != nil {
    if strings.Contains(err.Error(), "IPFS downloads are not supported") {
        // rewrite DownloadSources to HTTPS only
    }
}

When it happens

Trigger: Calling GetMigrationFetcher (or RunHybridMigrations) with DownloadSources containing the literal string "IPFS" (any case) while operating on a legacy repo version <16, or with a custom sources list that includes IPFS alongside HTTPS.

Common situations: Users copying a modern config (where IPFS downloads are supported for newer migrations) onto an old repo; adding "IPFS" to Migration.DownloadSources expecting it to be ignored or work for all versions.

Related errors

• unknown config value, Migrations.Keep must be 'cache', 'pin'
• bad gateway address: %w
• bad gateway address: url scheme must be http or https
• abort failed: close: %w, remove: %v
• source field %s does not exist

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