ipfs/kubo · critical

migration %s failed: %w

Error message

migration %s failed: %w

What it means

RunMigration executed one of the fetched/bundled fs-repo migration binaries and it exited with an error; the message names which migration step failed and wraps its output. The repo may be mid-migration, so a backup matters.

Source

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

		if err != nil {
			logger.Print("Failed to download migrations.")
			return err
		}

		for i := range missing {
			binPaths[missing[i]] = fetched[i]
		}
	}

	var revert bool
	if fromVer > targetVer {
		revert = true
	}
	for _, migration := range migrations {
		logger.Println("Running migration", migration, "...")
		err = runMigration(ctx, binPaths[migration], ipfsDir, revert, logger)
		if err != nil {
			return fmt.Errorf("migration %s failed: %w", migration, err)
		}
	}
	logger.Printf("Success: fs-repo migrated to version %d.\n", targetVer)

	return nil
}

func NeedMigration(target int) (bool, error) {
	vnum, err := RepoVersion("")
	if err != nil {
		return false, fmt.Errorf("could not get repo version: %w", err)
	}

	return vnum != target, nil
}

func ExeName(name string) string {
	if runtime.GOOS == "windows" {

View on GitHub (pinned to 329838acdf)

Solutions

1. Read the wrapped underlying error and the migration binary's output to identify the failing step.
2. Stop any running ipfs daemon so the repo is not locked, then retry.
3. Ensure adequate disk space and correct ownership/permissions on the repo directory.
4. Restore the repo from the backup taken before migration and retry the migration cleanly.

Example fix

// before
# run migration while daemon is running -> fails
// after
ipfs shutdown  # or kill daemon
fs-repo-migrations

// ensure no daemon holds the lock and enough disk space
if out, err := exec.Command("pgrep", "-f", "ipfs daemon").Output(); err == nil {
    return errors.New("stop the ipfs daemon before migrating")
}

if err := RunMigration(ctx, cfg, ipfsDir, from, to, false); err != nil {
    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        log.Printf("migration binary failed: %v", err) // inspect wrapped cause
    }
}

When it happens

Trigger: runMigration executes the migration binary for a version step and it returns non-zero: bad flags, missing repo lock, corrupted data, insufficient disk space, or the binary itself crashed.

Common situations: Interrupted previous migration leaving the repo half-converted; running as a different user than the repo owner so the migration cannot write; daemon still running and holding the repo lock; out-of-space disk during migration.

Related errors

• abort failed: close: %w, remove: %v
• source field %s does not exist
• %q is not a file
• failed to get temp dir: %s
• failed to initialize ephemeral node: %s

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