{"record":{"id":"c7350bb9ea4e506c","repo":"ipfs/kubo","slug":"failed-to-download-migrations-s","errorCode":null,"errorMessage":"failed to download migrations: %s","messagePattern":"failed to download migrations: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":313,"sourceCode":"\t\t\tloc, err := FetchBinary(ctx, fetcher, dist, ver, name, destDir)\n\t\t\tif err != nil {\n\t\t\t\tlogger.Printf(\"could not download %s: %s\", name, err)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tlogger.Printf(\"Downloaded and unpacked migration: %s (%s)\", loc, ver)\n\t\t\tbins[i] = loc\n\t\t}(i, name)\n\t}\n\twg.Wait()\n\n\tvar fails []string\n\tfor i := range bins {\n\t\tif bins[i] == \"\" {\n\t\t\tfails = append(fails, needed[i])\n\t\t}\n\t}\n\tif len(fails) != 0 {\n\t\terr = fmt.Errorf(\"failed to download migrations: %s\", strings.Join(fails, \" \"))\n\t\tif ctx.Err() != nil {\n\t\t\terr = fmt.Errorf(\"%s, %w\", ctx.Err(), err)\n\t\t}\n\t\treturn nil, err\n\t}\n\n\treturn bins, nil\n}\n\n// RunHybridMigrations intelligently runs migrations using external tools for legacy versions\n// and embedded migrations for modern versions. This handles the transition from external\n// fs-repo-migrations binaries (for repo versions <16) to embedded migrations (for repo versions ≥16).\n//\n// The function automatically:\n// 1. Uses external migrations to get from current version to v16 (if needed)\n// 2. Uses embedded migrations for v16+ steps\n// 3. Handles pure external, pure embedded, or mixed migration scenarios\n//","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L295-L331","documentation":"After downloading all requested migration binaries concurrently, fetchMigrations checks each result; any empty entry means that migration failed to download/unpack. It aggregates all missing binaries into a single error listing them, so the user sees every failed migration at once.","triggerScenarios":"One or more migration binaries named in `needed` failed to download: network errors, 404 from the distribution server, corrupted archives, or download workers returning empty paths on error.","commonSituations":"Dist server unreachable or behind a proxy/firewall; requested migration version doesn't exist (e.g. migrating across a very old repo version); disk full in the destination directory; corporate proxies blocking dist.ipfs.tech.","solutions":["Check network access to the distribution endpoint (dist.ipfs.tech or IPFS_DIST_PATH mirror) with curl","Read the full error: each listed name is a migration that failed; check individual download errors logged during the run","Retry with a stable connection, or pre-download migration binaries into the migrations directory or PATH","Verify the destination directory (IPFS_PATH) has write space and permissions"],"exampleFix":"// before\n// rely on daemon auto-migration in a hermetic CI job\n// after\n// pre-fetch binaries or verify reachability first\ncurl -fIsS https://dist.ipfs.tech/fs-repo-migrations || (echo \"dist unreachable\"; exit 1)\nipfs daemon --migrate","handlingStrategy":"retry","validationCode":"for _, m := range needed {\n    if _, err := os.Stat(filepath.Join(destDir, m)); err == nil { continue }\n    resp, err := http.Head(distURL + \"/\" + m)\n    if err != nil || resp.StatusCode != 200 { log.Printf(\"unreachable: %s\", m) }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.HasPrefix(err.Error(), \"failed to download migrations:\") {\n    failed := strings.TrimPrefix(err.Error(), \"failed to download migrations: \")\n    log.Printf(\"retry these after checking network: %s\", failed)\n}","preventionTips":["Verify dist endpoint reachability before starting long migrations","Ensure adequate disk space in IPFS_PATH","Retry transient network failures with backoff","Pre-download binaries for air-gapped or flaky environments"],"tags":["migrations","network-download","aggregate-error"],"backgroundTag":"migration-download-failed","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"}