could not determine external migration paths: %w

Error message

could not determine external migration paths: %w

What it means

In the hybrid path (current < 16, target >= 16), phase 1 uses external migration binaries to reach v16. RunHybridMigrations wraps any findMigrations failure during this phase with this message, distinguishing it from the pure-external case.

Source

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

		if err != nil {
			return fmt.Errorf("failed to get migration fetcher: %w", err)
		}
		defer fetcher.Close()
		return RunMigration(ctx, fetcher, targetVer, ipfsDir, allowDowngrade)
	}

	// Case 3: Hybrid migration (current < 16, target ≥ 16)
	if needsExternal && needsEmbedded {
		logger.Printf("Starting hybrid migration from version %d to %d", currentVer, targetVer)
		logger.Print("Using hybrid migration strategy: external to v16, then embedded")

		// Phase 1: Use external migrations to get to v16
		logger.Printf("Phase 1: External migration from v%d to v%d", currentVer, embeddedMigrationsMinVersion)

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

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

		if foundAll {
			if err = runMigrationsFromPath(ctx, migrations, binPaths, ipfsDir, logger, false); err != nil {
				return fmt.Errorf("external migration phase failed: %w", err)
			}
		} else {
			migrationCfg, err := ReadMigrationConfig(ipfsDir, "")
			if err != nil {
				return fmt.Errorf("could not read migration config: %w", err)

View on GitHub (pinned to 329838acdf)

Solutions

Install fs-repo-migrations and ensure its binaries are on PATH for the daemon's environment
Check systemd service Environment/PATH if running under systemd — PATH there is minimal
Pre-download phase-1 migration binaries into the repo's migrations directory
Read the wrapped inner error for the precise lookup failure

Example fix

# before: systemd unit with no PATH to migration binaries
ExecStart=/usr/local/bin/ipfs daemon --migrate
# after
[Service]
Environment=PATH=/usr/local/bin:/usr/bin:/root/go/bin
ExecStart=/usr/local/bin/ipfs daemon --migrate

Defensive patterns

Strategy: fallback

Validate before calling

mig, paths, err := migration.FindMigrations(ctx, cur, 16)
if err != nil || len(paths) < len(mig) {
    log.Println("phase-1 external binaries missing; install fs-repo-migrations")
}

Try / catch

if err != nil && strings.Contains(err.Error(), "could not determine external migration paths") {
    return fmt.Errorf("install fs-repo-migrations (PATH or migrations dir) for the v%d->v16 phase: %w", cur, err)
}

Prevention

For upgrades from very old repos, install fs-repo-migrations first
Fix daemon PATH (systemd units often have minimal PATH)
Pre-place phase-1 binaries in the repo migrations directory
Dry-run the hybrid migration on a copy of the repo

When it happens

Trigger: findMigrations(ctx, currentVer, 16) errors while resolving binaries for the first phase — e.g. invalid version inputs, errors scanning PATH/migrations directory, or context cancellation.

Common situations: Upgrading very old repos (e.g. v9) to a modern kubo on machines without fs-repo-migrations installed; broken PATH in systemd unit files; permission issues on the migrations directory.

Related errors

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