What causes "could not determine migration paths: %w" in ipfs/kubo?

Inspect the wrapped inner error for the actual cause

could not determine migration paths: %w

Error message

could not determine migration paths: %w

What it means

For a purely external migration (target < 16), RunHybridMigrations calls findMigrations to enumerate required fs-repo-migration binaries (checking PATH and the migrations dir). If that lookup itself fails, the error is wrapped with this message.

Source

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

	// Determine migration strategy based on version ranges
	needsExternal := currentVer < embeddedMigrationsMinVersion
	needsEmbedded := targetVer >= embeddedMigrationsMinVersion

	// Case 1: Pure embedded migration (both current and target ≥ 16)
	if !needsExternal && needsEmbedded {
		return RunEmbeddedMigrations(ctx, targetVer, ipfsDir, allowDowngrade)
	}

	// For cases requiring external migrations, we check if migration binaries
	// are available in PATH before attempting network downloads

	// Case 2: Pure external migration (target < 16)
	if needsExternal && !needsEmbedded {

		// Check for migration binaries in PATH first (for testing/local development)
		migrations, binPaths, err := findMigrations(ctx, currentVer, targetVer)
		if err != nil {
			return fmt.Errorf("could not determine migration paths: %w", err)
		}

		foundAll := true
		for _, migName := range migrations {
			if _, exists := binPaths[migName]; !exists {
				foundAll = false
				break
			}
		}

		if foundAll {
			return runMigrationsFromPath(ctx, migrations, binPaths, ipfsDir, logger, false)
		}

		// Fall back to network download (original behavior)
		migrationCfg, err := ReadMigrationConfig(ipfsDir, "")
		if err != nil {
			return fmt.Errorf("could not read migration config: %w", err)

View on GitHub (pinned to 329838acdf)

Solutions

Inspect the wrapped inner error for the actual cause
Install fs-repo-migrations so binaries are discoverable in PATH
Pre-download the needed migration binaries into IPFS_PATH's migrations directory
Re-run with a longer-lived context and correct repo path

Example fix

// before
ipfs daemon --migrate  # fails: could not determine migration paths
// after
go install github.com/ipfs/fs-repo-migrations/fs-repo-migrations@latest
export PATH="$PATH:$(go env GOPATH)/bin"
ipfs daemon --migrate

Defensive patterns

Strategy: validation

Validate before calling

mig, paths, err := migration.FindMigrations(ctx, cur, target) // or check manually
if err != nil || len(paths) < len(mig) {
    log.Println("install fs-repo-migrations or pre-download binaries")
}

Try / catch

if err != nil && strings.Contains(err.Error(), "could not determine migration paths") {
    return fmt.Errorf("install fs-repo-migrations in PATH: %w", err)
}

Prevention

Install fs-repo-migrations wherever the daemon runs
Ensure PATH includes the migration binaries in daemon environments (systemd, Docker)
Pre-download needed binaries into the repo migrations dir
Test the migration path in staging before production upgrades

When it happens

Trigger: findMigrations returns an error while resolving migration names for currentVer→targetVer, e.g. an invalid version pair, failures listing the migrations directory, or context cancellation during lookup.

Common situations: Very old repos (pre-v10) requiring many migration binaries; unusual IPFS_PATH permissions; context timeouts during daemon startup.

Related errors

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