ipfs/kubo · error

migration binary %s not found in PATH

Error message

migration binary %s not found in PATH

What it means

Hybrid migration wanted to run a migration binary that was expected in PATH but was not found there (binPaths had no fetched copy either); the needed fs-repo-migrations binary is simply missing on this machine.

Source

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

			}
			defer fetcher.Close()

			if err = RunMigration(ctx, fetcher, targetVer, ipfsDir, allowDowngrade); err != nil {
				return fmt.Errorf("external downgrade phase failed: %w", err)
			}
		}
	}

	logger.Printf("Reverse hybrid migration completed successfully: v%d → v%d", currentVer, targetVer)
	return nil
}

// runMigrationsFromPath runs migrations using binaries found in PATH
func runMigrationsFromPath(ctx context.Context, migrations []string, binPaths map[string]string, ipfsDir string, logger *log.Logger, revert bool) error {
	for _, migName := range migrations {
		binPath, exists := binPaths[migName]
		if !exists {
			return fmt.Errorf("migration binary %s not found in PATH", migName)
		}

		logger.Printf("Running migration %s using binary from PATH: %s", migName, binPath)

		// Run the migration binary directly
		err := runMigration(ctx, binPath, ipfsDir, revert, logger)
		if err != nil {
			return fmt.Errorf("migration %s failed: %w", migName, err)
		}
	}
	return nil
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Install fs-repo-migrations and ensure the binaries are in PATH (https://github.com/ipfs/fs-repo-migrations)
2. Or let kubo download the migrations by not disabling the fetch step
3. Verify PATH inside the environment where the daemon/CLI runs

When it happens

Trigger: Thrown at repo/fsrepo/migrations/migrations.go:530 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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