{"record":{"id":"f1efdbab7297734c","repo":"ipfs/kubo","slug":"downgrade-from-version-d-to-d-requires-allowdown","errorCode":null,"errorMessage":"downgrade from version %d to %d requires allowDowngrade=true","messagePattern":"downgrade from version (.+?) to (.+?) requires allowDowngrade=true","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":360,"sourceCode":"\tconst embeddedMigrationsMinVersion = 16\n\n\t// Get current repo version\n\tcurrentVer, err := RepoVersion(ipfsDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"could not get current repo version: %w\", err)\n\t}\n\n\tvar logger = log.New(os.Stdout, \"\", 0)\n\n\t// Check if migration is needed\n\tif currentVer == targetVer {\n\t\tlogger.Printf(\"Repository is already at version %d\", targetVer)\n\t\treturn nil\n\t}\n\n\t// Validate downgrade request\n\tif targetVer < currentVer && !allowDowngrade {\n\t\treturn fmt.Errorf(\"downgrade from version %d to %d requires allowDowngrade=true\", currentVer, targetVer)\n\t}\n\n\t// Determine migration strategy based on version ranges\n\tneedsExternal := currentVer < embeddedMigrationsMinVersion\n\tneedsEmbedded := targetVer >= embeddedMigrationsMinVersion\n\n\t// Case 1: Pure embedded migration (both current and target ≥ 16)\n\tif !needsExternal && needsEmbedded {\n\t\treturn RunEmbeddedMigrations(ctx, targetVer, ipfsDir, allowDowngrade)\n\t}\n\n\t// For cases requiring external migrations, we check if migration binaries\n\t// are available in PATH before attempting network downloads\n\n\t// Case 2: Pure external migration (target < 16)\n\tif needsExternal && !needsEmbedded {\n\n\t\t// Check for migration binaries in PATH first (for testing/local development)","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L342-L378","documentation":"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.","triggerScenarios":"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.","commonSituations":"Downgrading the kubo binary (pinning an older release) after the repo was migrated; Docker image rollbacks; staging rollback after a bad upgrade.","solutions":["Re-run with allowDowngrade=true (CLI: `ipfs daemon --migrate --allow-downgrade`) if the data loss risk is acceptable","Keep using the newer kubo binary that matches the current repo version","Back up IPFS_PATH before any forced downgrade","Check `ipfs repo version` to confirm which binary version you need"],"exampleFix":"// before\nipfs daemon --migrate            # with older binary, repo is newer\n// after\nipfs daemon --migrate --allow-downgrade   # after backing up IPFS_PATH","handlingStrategy":"validation","validationCode":"cur, _ := migration.RepoVersion(ipfsDir)\nif target < cur && !allowDowngrade {\n    return fmt.Errorf(\"would downgrade %d -> %d; pass allowDowngrade=true or use matching binary\", cur, target)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"requires allowDowngrade=true\") {\n    return fmt.Errorf(\"either upgrade your kubo binary or re-run with --allow-downgrade (backup first!): %w\", err)\n}","preventionTips":["Match the kubo binary version to the repo version before starting","Back up IPFS_PATH before any downgrade","Use --allow-downgrade only deliberately, never in scripts","Check `ipfs repo version` in deployment tooling before rollback"],"tags":["migrations","downgrade","safety-guard"],"backgroundTag":"downgrade-requires-allow-flag","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}