ipfs/kubo · error

downgrade not allowed from %d to %d

Error message

downgrade not allowed from %d to %d

What it means

The repo's current version is higher than the requested target version and allowDowngrade was false. Migrations refuse to move the fs-repo backward by default because older binaries cannot read newer repo formats.

Source

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

//
// Deprecated: This function downloads migration binaries from the internet and will be removed
// in a future version. Use RunHybridMigrations for modern migrations with embedded support,
// or RunEmbeddedMigrations for repo versions ≥16.
func RunMigration(ctx context.Context, fetcher Fetcher, targetVer int, ipfsDir string, allowDowngrade bool) error {
	ipfsDir, err := CheckIpfsDir(ipfsDir)
	if err != nil {
		return err
	}
	fromVer, err := RepoVersion(ipfsDir)
	if err != nil {
		return fmt.Errorf("could not get repo version: %w", err)
	}
	if fromVer == targetVer {
		// repo already at target version number
		return nil
	}
	if fromVer > targetVer && !allowDowngrade {
		return fmt.Errorf("downgrade not allowed from %d to %d", fromVer, targetVer)
	}

	logger := log.New(os.Stdout, "", 0)

	logger.Print("Looking for suitable migration binaries.")

	migrations, binPaths, err := findMigrations(ctx, fromVer, targetVer)
	if err != nil {
		return err
	}

	// Download migrations that were not found
	if len(binPaths) < len(migrations) {
		missing := make([]string, 0, len(migrations)-len(binPaths))
		for _, mig := range migrations {
			if _, ok := binPaths[mig]; !ok {
				missing = append(missing, mig)
			}

View on GitHub (pinned to 329838acdf)

Solutions

1. If a downgrade is truly intended, call RunMigration with allowDowngrade=true (accepting older-format migration).
2. Otherwise upgrade the ipfs binary back to a version matching the repo and pass the correct targetVer.
3. Back up the repo before performing any downgrade migration.

Example fix

// before
RunMigration(ctx, cfg, ipfsDir, 16, 15, false)
// after
RunMigration(ctx, cfg, ipfsDir, 16, 15, true) // allowDowngrade=true

fromVer, _ := migrations.RepoVersion(ipfsDir)
if fromVer > targetVer && !allowDowngrade {
    // refuse or set allowDowngrade=true explicitly
}

if err != nil {
    if strings.Contains(err.Error(), "downgrade not allowed") {
        // prompt user or pass allowDowngrade=true
    }
}

When it happens

Trigger: Calling RunMigration with targetVer < current repo version and allowDowngrade=false, e.g. downgrading the ipfs binary and letting it auto-migrate the repo backward, or passing a wrong (older) target version number.

Common situations: Downgrading kubo after having migrated the repo forward; pinning an old ipfs version in a container while the repo volume was migrated by a newer one; a test or script hardcoding an outdated target version.

Related errors

• embedded downgrade phase failed: %w
• external downgrade phase failed: %w
• abort failed: close: %w, remove: %v
• source field %s does not exist
• %q is not a file

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