ipfs/kubo · error

ErrNeedMigration

ErrNeedMigration

Error message

ipfs repo needs migration, please run migration tool.

What it means

Sentinel ErrNeedMigration: the on-disk repo's version is lower than RepoVersion, i.e. the repo was created by an older kubo and must be migrated before this binary can open it. The daemon detects this and offers to run migrations automatically.

Source

Thrown at repo/fsrepo/fsrepo.go:54

var log = logging.Logger("fsrepo")

// RepoVersion is the version number that we are currently expecting to see.
var RepoVersion = version.RepoVersion

var migrationInstructions = `See https://github.com/ipfs/fs-repo-migrations/blob/master/run.md
Sorry for the inconvenience. In the future, these will run automatically.`

var programTooLowMessage = `Your programs version (%d) is lower than your repos (%d).
Please update ipfs to a version that supports the existing repo, or run
a migration in reverse.

See https://github.com/ipfs/fs-repo-migrations/blob/master/run.md for details.`

var (
	ErrNoVersion     = errors.New("no version file found, please run 0-to-1 migration tool.\n" + migrationInstructions)
	ErrOldRepo       = errors.New("ipfs repo found in old '~/.go-ipfs' location, please run migration tool.\n" + migrationInstructions)
	ErrNeedMigration = errors.New("ipfs repo needs migration, please run migration tool.\n" + migrationInstructions)
)

type NoRepoError struct {
	Path string
}

var _ error = NoRepoError{}

func (err NoRepoError) Error() string {
	return fmt.Sprintf("no IPFS repo found in %s.\nplease run: 'ipfs init'", err.Path)
}

const (
	apiFile      = "api"
	gatewayFile  = "gateway"
	swarmKeyFile = "swarm.key"
)

View on GitHub (pinned to 329838acdf)

Solutions

1. Let the daemon run the migration automatically (answer the prompt / ensure no illegal downgrade)
2. Or run 'ipfs repo migrate' / fs-repo-migrations manually first
3. Keep a backup of $IPFS_PATH before migrating

When it happens

Trigger: Thrown at repo/fsrepo/fsrepo.go:54 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/503d85d3c7d83dcc. Report an issue: GitHub.