{"record":{"id":"c6c309f731b66a5e","repo":"ipfs/kubo","slug":"ipfs-downloads-are-not-supported-for-legacy-migrat","errorCode":null,"errorMessage":"IPFS downloads are not supported for legacy migrations (repo versions <16). Please use only HTTPS in Migration.DownloadSources","messagePattern":"IPFS downloads are not supported for legacy migrations \\(repo versions <16\\)\\. Please use only HTTPS in Migration\\.DownloadSources","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":181,"sourceCode":"//\n// Deprecated: This function is used by legacy migration downloads and will be removed\n// in a future version. Use RunHybridMigrations or RunEmbeddedMigrations instead.\nfunc GetMigrationFetcher(downloadSources []string, distPath string, newIpfsFetcher func(string) Fetcher) (Fetcher, error) {\n\tconst httpUserAgent = \"kubo/migration\"\n\n\tvar fetchers []Fetcher\n\tfor _, src := range downloadSources {\n\t\tsrc := strings.TrimSpace(src)\n\t\tswitch src {\n\t\tcase \"HTTPS\", \"https\", \"HTTP\", \"http\":\n\t\t\t// Expand the alias into the full ordered list of trustless\n\t\t\t// community-provided gateways so migration survives a\n\t\t\t// single-gateway outage.\n\t\t\tfor _, gw := range defaultMigrationGateways {\n\t\t\t\tfetchers = append(fetchers, NewHttpFetcher(distPath, gw, httpUserAgent, 0))\n\t\t\t}\n\t\tcase \"IPFS\", \"ipfs\":\n\t\t\treturn nil, errors.New(\"IPFS downloads are not supported for legacy migrations (repo versions <16). Please use only HTTPS in Migration.DownloadSources\")\n\t\tcase \"\":\n\t\t\t// Ignore empty string\n\t\tdefault:\n\t\t\tu, err := url.Parse(src)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"bad gateway address: %w\", err)\n\t\t\t}\n\t\t\tswitch u.Scheme {\n\t\t\tcase \"\":\n\t\t\t\tu.Scheme = \"https\"\n\t\t\tcase \"https\", \"http\":\n\t\t\tdefault:\n\t\t\t\treturn nil, errors.New(\"bad gateway address: url scheme must be http or https\")\n\t\t\t}\n\t\t\tfetchers = append(fetchers, NewHttpFetcher(distPath, u.String(), httpUserAgent, 0))\n\t\t}\n\t}\n","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L163-L199","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove \"IPFS\" from Migration.DownloadSources, keeping only HTTPS entries.","Run `ipfs config --json Migration.DownloadSources '[\"HTTPS\"]'`.","If IPFS-based fetching is required, first upgrade the repo through supported HTTPS migrations."],"exampleFix":"// before\nipfs config --json Migration.DownloadSources '[\"IPFS\",\"HTTPS\"]'\n// after\nipfs config --json Migration.DownloadSources '[\"HTTPS\"]'","handlingStrategy":"validation","validationCode":"for _, src := range cfg.Migration.DownloadSources {\n    if strings.EqualFold(src, \"IPFS\") {\n        return errors.New(\"IPFS source unsupported for repo versions <16\")\n    }\n}","typeGuard":null,"tryCatchPattern":"fetcher, err := cmd.GetMigrationFetcher(...)\nif err != nil {\n    if strings.Contains(err.Error(), \"IPFS downloads are not supported\") {\n        // rewrite DownloadSources to HTTPS only\n    }\n}","preventionTips":["Keep Migration.DownloadSources as [\"HTTPS\"] for legacy repos","Check repo version before enabling IPFS-based fetching","Validate DownloadSources entries at config-write time"],"tags":["migrations","config-validation","download-sources","go"],"backgroundTag":"unsupported-download-source","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}