ipfs/kubo · error

fs-repo requires migration

Error message

fs-repo requires migration

What it means

The daemon detected that the fs-repo on disk was written by an older kubo version and requires migrations. Because the user declined (or could not confirm) running them now, the daemon refuses to start and returns this error to signal the repo version gap.

Source

Thrown at cmd/ipfs/kubo/daemon.go:358

		// Get current repo version for more informative message
		currentVersion, verErr := migrations.RepoVersion(cctx.ConfigRoot)
		if verErr != nil {
			// Fallback to generic message if we can't read version
			fmt.Printf("Kubo repository at %s requires migration.\n", cctx.ConfigRoot)
		} else {
			fmt.Printf("Kubo repository at %s has version %d and needs to be migrated to version %d.\n",
				cctx.ConfigRoot, currentVersion, version.RepoVersion)
		}

		if !found {
			domigrate = YesNoPrompt("Run migrations now? [y/N]")
		}
		close(migrationDone)

		if !domigrate {
			fmt.Printf("Not running migrations on repository at %s. Re-run daemon with --migrate or see 'ipfs repo migrate --help'\n", cctx.ConfigRoot)
			return errors.New("fs-repo requires migration")
		}

		// Use hybrid migration strategy that intelligently combines external and embedded migrations
		// Use req.Context instead of cctx.Context() to avoid attempting repo open before migrations complete
		err = migrations.RunHybridMigrations(req.Context, version.RepoVersion, cctx.ConfigRoot, false)
		if err != nil {
			fmt.Println("Repository migration failed:")
			fmt.Printf("  %s\n", err)
			fmt.Println("If you think this is a bug, please file an issue and include this whole log output.")
			fmt.Println("  https://github.com/ipfs/kubo")
			return err
		}

		// Note: Migration caching/pinning functionality has been deprecated
		// The hybrid migration system handles legacy migrations more efficiently

		repo, err = fsrepo.Open(cctx.ConfigRoot)
		if err != nil {

View on GitHub (pinned to 329838acdf)

Solutions

1. Run `ipfs daemon --migrate` to apply the migrations automatically before startup
2. Run migrations explicitly: `ipfs repo migrate` (see `ipfs repo migrate --help`)
3. In non-interactive environments set the affirmative flag/env for auto-migration instead of relying on the prompt
4. Pin the previous kubo version if you cannot migrate yet (repo is forward-compatible only)
5. Back up IPFS_PATH (config + datastore) before migrating

// compare repo and binary versions before starting the daemon
out, _ := exec.Command("ipfs", "repo", "version").Output()
repoVer := strings.TrimSpace(string(out))
_ = repoVer // if lower than the binary's RepoVersion, migrate first

When it happens

Trigger: Starting `ipfs daemon` on an IPFS_PATH whose repo version is lower than version.RepoVersion, and answering 'n' to 'Run migrations now?' (or running without --migrate in a non-interactive context where the prompt resolves to no).

Common situations: Upgrading the kubo binary across a repo-version boundary without migrating; running the daemon non-interactively (scripts, containers, systemd) where the y/N prompt defaults to no; sharing one IPFS_PATH between kubo versions.

Related errors

• cannot get migrations from unknown fetcher type
• nothing downloaded by ipfs fetcher
• could not get repo version: %w
• could not get current repo version: %w
• ipfs api address could not be found

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