{"record":{"id":"59f2b92d051935bc","repo":"ipfs/kubo","slug":"downgrade-not-allowed-from-d-to-d","errorCode":null,"errorMessage":"downgrade not allowed from %d to %d","messagePattern":"downgrade not allowed from (.+?) to (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":46,"sourceCode":"//\n// Deprecated: This function downloads migration binaries from the internet and will be removed\n// in a future version. Use RunHybridMigrations for modern migrations with embedded support,\n// or RunEmbeddedMigrations for repo versions ≥16.\nfunc RunMigration(ctx context.Context, fetcher Fetcher, targetVer int, ipfsDir string, allowDowngrade bool) error {\n\tipfsDir, err := CheckIpfsDir(ipfsDir)\n\tif err != nil {\n\t\treturn err\n\t}\n\tfromVer, err := RepoVersion(ipfsDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"could not get repo version: %w\", err)\n\t}\n\tif fromVer == targetVer {\n\t\t// repo already at target version number\n\t\treturn nil\n\t}\n\tif fromVer > targetVer && !allowDowngrade {\n\t\treturn fmt.Errorf(\"downgrade not allowed from %d to %d\", fromVer, targetVer)\n\t}\n\n\tlogger := log.New(os.Stdout, \"\", 0)\n\n\tlogger.Print(\"Looking for suitable migration binaries.\")\n\n\tmigrations, binPaths, err := findMigrations(ctx, fromVer, targetVer)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// Download migrations that were not found\n\tif len(binPaths) < len(migrations) {\n\t\tmissing := make([]string, 0, len(migrations)-len(binPaths))\n\t\tfor _, mig := range migrations {\n\t\t\tif _, ok := binPaths[mig]; !ok {\n\t\t\t\tmissing = append(missing, mig)\n\t\t\t}","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L28-L64","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If a downgrade is truly intended, call RunMigration with allowDowngrade=true (accepting older-format migration).","Otherwise upgrade the ipfs binary back to a version matching the repo and pass the correct targetVer.","Back up the repo before performing any downgrade migration."],"exampleFix":"// before\nRunMigration(ctx, cfg, ipfsDir, 16, 15, false)\n// after\nRunMigration(ctx, cfg, ipfsDir, 16, 15, true) // allowDowngrade=true","handlingStrategy":"validation","validationCode":"fromVer, _ := migrations.RepoVersion(ipfsDir)\nif fromVer > targetVer && !allowDowngrade {\n    // refuse or set allowDowngrade=true explicitly\n}","typeGuard":null,"tryCatchPattern":"if err != nil {\n    if strings.Contains(err.Error(), \"downgrade not allowed\") {\n        // prompt user or pass allowDowngrade=true\n    }\n}","preventionTips":["Compare RepoVersion against the binary's expected version before migrating","Always pass allowDowngrade explicitly and deliberately","Back up the repo before any downgrade"],"tags":["migrations","downgrade","versioning","go"],"backgroundTag":"repo-downgrade-not-allowed","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"}