ipfs/kubo · error

downgrade from version %d to %d requires allowDowngrade=true

Error message

downgrade from version %d to %d requires allowDowngrade=true

What it means

RunHybridMigrations refuses to downgrade the repository to an older version unless allowDowngrade is explicitly true, because downgrading can lose data or break newer features. The error names the exact from/to versions.

Source

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

	const embeddedMigrationsMinVersion = 16

	// Get current repo version
	currentVer, err := RepoVersion(ipfsDir)
	if err != nil {
		return fmt.Errorf("could not get current repo version: %w", err)
	}

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

	// Check if migration is needed
	if currentVer == targetVer {
		logger.Printf("Repository is already at version %d", targetVer)
		return nil
	}

	// Validate downgrade request
	if targetVer < currentVer && !allowDowngrade {
		return fmt.Errorf("downgrade from version %d to %d requires allowDowngrade=true", currentVer, targetVer)
	}

	// Determine migration strategy based on version ranges
	needsExternal := currentVer < embeddedMigrationsMinVersion
	needsEmbedded := targetVer >= embeddedMigrationsMinVersion

	// Case 1: Pure embedded migration (both current and target ≥ 16)
	if !needsExternal && needsEmbedded {
		return RunEmbeddedMigrations(ctx, targetVer, ipfsDir, allowDowngrade)
	}

	// For cases requiring external migrations, we check if migration binaries
	// are available in PATH before attempting network downloads

	// Case 2: Pure external migration (target < 16)
	if needsExternal && !needsEmbedded {

		// Check for migration binaries in PATH first (for testing/local development)

View on GitHub (pinned to 329838acdf)

Solutions

1. Re-run with allowDowngrade=true (CLI: `ipfs daemon --migrate --allow-downgrade`) if the data loss risk is acceptable
2. Keep using the newer kubo binary that matches the current repo version
3. Back up IPFS_PATH before any forced downgrade
4. Check `ipfs repo version` to confirm which binary version you need

Example fix

// before
ipfs daemon --migrate            # with older binary, repo is newer
// after
ipfs daemon --migrate --allow-downgrade   # after backing up IPFS_PATH

cur, _ := migration.RepoVersion(ipfsDir)
if target < cur && !allowDowngrade {
    return fmt.Errorf("would downgrade %d -> %d; pass allowDowngrade=true or use matching binary", cur, target)
}

if err != nil && strings.Contains(err.Error(), "requires allowDowngrade=true") {
    return fmt.Errorf("either upgrade your kubo binary or re-run with --allow-downgrade (backup first!): %w", err)
}

When it happens

Trigger: Running RunHybridMigrations with targetVer < currentVer and allowDowngrade=false — e.g. starting an older kubo binary against a repo already migrated to a newer version, without the --allow-downgrade flag.

Common situations: Downgrading the kubo binary (pinning an older release) after the repo was migrated; Docker image rollbacks; staging rollback after a bad upgrade.

Related errors

• downgrade not allowed from %d to %d
• embedded downgrade phase failed: %w
• external downgrade phase failed: %w
• cannot get migrations from unknown fetcher type
• nothing downloaded by ipfs fetcher

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