What causes "failed to download migrations: %s" in ipfs/kubo?

Check network access to the distribution endpoint (dist.ipfs.tech or IPFS_DIST_PATH mirror) with curl

failed to download migrations: %s

Error message

failed to download migrations: %s

What it means

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.

Source

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

			loc, err := FetchBinary(ctx, fetcher, dist, ver, name, destDir)
			if err != nil {
				logger.Printf("could not download %s: %s", name, err)
				return
			}
			logger.Printf("Downloaded and unpacked migration: %s (%s)", loc, ver)
			bins[i] = loc
		}(i, name)
	}
	wg.Wait()

	var fails []string
	for i := range bins {
		if bins[i] == "" {
			fails = append(fails, needed[i])
		}
	}
	if len(fails) != 0 {
		err = fmt.Errorf("failed to download migrations: %s", strings.Join(fails, " "))
		if ctx.Err() != nil {
			err = fmt.Errorf("%s, %w", ctx.Err(), err)
		}
		return nil, err
	}

	return bins, nil
}

// RunHybridMigrations intelligently runs migrations using external tools for legacy versions
// and embedded migrations for modern versions. This handles the transition from external
// fs-repo-migrations binaries (for repo versions <16) to embedded migrations (for repo versions ≥16).
//
// The function automatically:
// 1. Uses external migrations to get from current version to v16 (if needed)
// 2. Uses embedded migrations for v16+ steps
// 3. Handles pure external, pure embedded, or mixed migration scenarios
//

View on GitHub (pinned to 329838acdf)

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

Example fix

// before
// rely on daemon auto-migration in a hermetic CI job
// after
// pre-fetch binaries or verify reachability first
curl -fIsS https://dist.ipfs.tech/fs-repo-migrations || (echo "dist unreachable"; exit 1)
ipfs daemon --migrate

Defensive patterns

Strategy: retry

Validate before calling

for _, m := range needed {
    if _, err := os.Stat(filepath.Join(destDir, m)); err == nil { continue }
    resp, err := http.Head(distURL + "/" + m)
    if err != nil || resp.StatusCode != 200 { log.Printf("unreachable: %s", m) }
}

Try / catch

if err != nil && strings.HasPrefix(err.Error(), "failed to download migrations:") {
    failed := strings.TrimPrefix(err.Error(), "failed to download migrations: ")
    log.Printf("retry these after checking network: %s", failed)
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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