ErrNoVersion

ErrNoVersion

Error message

no version file found, please run 0-to-1 migration tool.

What it means

fsrepo.open reads the version file inside the repo directory; when that read fails with a not-exist error, ErrNoVersion is returned. It means the directory exists but has no version marker, so fsrepo cannot determine repo compatibility and refuses to operate. The message directs users to run the 0-to-1 migration tool or use a supporting version.

Source

Thrown at repo/fsrepo/fsrepo.go:52

// TODO rename repo lock and hide name.
const LockFile = "repo.lock"

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

Run the fs-repo-migrations tool starting at the 0-to-1 migration (see https://github.com/ipfs/fs-repo-migrations/blob/master/run.md)
If the directory is not a real repo, run `ipfs init` to create a fresh repo with a version file, or point IPFS_PATH at the correct repo
Restore the missing version file from backup if the repo was partially copied/deleted
Check you did not set IPFS_PATH to an empty or wrong directory

Example fix

// before (shell)
IPFS_PATH=/old/repo ipfs daemon  # error: no version file
// after (shell)
ipfs fs-repo-migrations -to 1    # or restore/init the repo
IPFS_PATH=/old/repo ipfs daemon

Defensive patterns

Strategy: try-catch

Validate before calling

// before opening via fsrepo
if _, err := os.Stat(filepath.Join(ipfsPath, "version")); os.IsNotExist(err) {
	// repo has no version file: run migrations or ipfs init first
}

Type guard

func repoHasVersion(path string) bool {
	_, err := os.Stat(filepath.Join(path, "version"))
	return err == nil
}

Try / catch

r, err := fsrepo.Open(ipfsPath)
if err != nil {
	if errors.Is(err, fsrepo.ErrNoVersion) {
		// run fs-repo-migrations or ipfs init; do not retry blindly
		return fmt.Errorf("%w (run fs-repo-migrations or ipfs init)", err)
	}
	if errors.Is(err, fsrepo.ErrNeedMigration) {
		// run the migration tool for this version gap
	}
	return err
}

Prevention

Never delete or omit the version file when copying repo directories
Use `ipfs init` to create new repos instead of hand-crafting directories
Run fs-repo-migrations whenever the kubo version requires a repo migration
Verify IPFS_PATH points at a complete repo before starting the daemon

When it happens

Trigger: Opening a repo (fsrepo.Open/openDatastoreAt path) at an IPFS_PATH that was initialized by a pre-1.0/very old ipfs or by a tool that created the directory without writing the version file; a partially deleted repo where the version file is gone.

Common situations: Pointing IPFS_PATH at an ancient ~/.go-ipfs-era repo; manually copying a repo directory but omitting hidden files like the version file; crash or manual cleanup leaving a truncated repo; mounting a volume with an incomplete repo.

Related errors

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