{"record":{"id":"801f18e073b60a47","repo":"ipfs/kubo","slug":"embedded-downgrade-phase-failed-w","errorCode":null,"errorMessage":"embedded downgrade phase failed: %w","messagePattern":"embedded downgrade phase failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":476,"sourceCode":"\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"embedded migration phase failed: %w\", err)\n\t\t}\n\n\t\tlogger.Printf(\"Hybrid migration completed successfully: v%d → v%d\", currentVer, targetVer)\n\t\treturn nil\n\t}\n\n\t// Case 4: Reverse hybrid migration (≥16 to <16)\n\t// Use embedded migrations for ≥16 steps, then external migrations for <16 steps\n\tlogger.Printf(\"Starting reverse hybrid migration from version %d to %d\", currentVer, targetVer)\n\tlogger.Print(\"Using reverse hybrid migration strategy: embedded to v16, then external\")\n\n\t// Phase 1: Use embedded migrations from current version down to v16 (if needed)\n\tif currentVer > embeddedMigrationsMinVersion {\n\t\tlogger.Printf(\"Phase 1: Embedded downgrade from v%d to v%d\", currentVer, embeddedMigrationsMinVersion)\n\t\terr = RunEmbeddedMigrations(ctx, embeddedMigrationsMinVersion, ipfsDir, allowDowngrade)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"embedded downgrade phase failed: %w\", err)\n\t\t}\n\t}\n\n\t// Phase 2: Use external migrations from v16 to target (if needed)\n\tif embeddedMigrationsMinVersion > targetVer {\n\t\tlogger.Printf(\"Phase 2: External downgrade from v%d to v%d\", embeddedMigrationsMinVersion, targetVer)\n\n\t\t// Check for external migration binaries in PATH first\n\t\tmigrations, binPaths, err := findMigrations(ctx, embeddedMigrationsMinVersion, targetVer)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"could not determine external migration paths: %w\", err)\n\t\t}\n\n\t\tfoundAll := true\n\t\tfor _, migName := range migrations {\n\t\t\tif _, exists := binPaths[migName]; !exists {\n\t\t\t\tfoundAll = false\n\t\t\t\tbreak","sourceCodeStart":458,"sourceCodeEnd":494,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L458-L494","documentation":"On the downgrade path, RunHybridMigrations first runs embedded migrations backwards from the current version down to the v16 floor via RunEmbeddedMigrations (before handing off to external migrations for older versions). If that embedded downgrade fails, the error is wrapped as \"embedded downgrade phase failed\". Downgrades are only attempted when allowDowngrade is true.","triggerScenarios":"Calling RunHybridMigrations with targetVer < currentVer and allowDowngrade==true, when currentVer > 16 and RunEmbeddedMigrations(ctx, 16, ipfsDir, allowDowngrade) fails: a rollback migration cannot convert newer repo data, the binary running the daemon is older than the repo, or I/O/context failure mid-step.","commonSituations":"User downgraded the ipfs binary (e.g. rolled back a release) while the repo was already migrated by a newer version and answered yes to the downgrade prompt; rollback migrations refuse lossy conversions of data written by the newer schema; interrupted downgrade leaves the repo at an intermediate version.","solutions":["Prefer not downgrading: re-install the newer ipfs binary matching the repo version instead of rolling the repo back","If downgrade is intended, back up the repo first, then re-run with allowDowngrade=true after fixing the underlying I/O error reported by %w","Check <ipfsDir>/version to see which step failed and run `ipfs fs-repo-migrations -to <ver>` manually for detailed output","If the newer schema stored data the old version cannot represent, export needed data (ipfs dag/ipns/pin exports) before downgrading"],"exampleFix":"// before (downgrade attempted against repo migrated by newer kubo)\nerr := migrations.RunHybridMigrations(ctx, 15, ipfsPath, true)\n// after (align binary with repo version instead of forcing downgrade)\nver, _ := migrations.RepoVersion(ipfsPath)\nif ver > 15 {\n\tlog.Fatalf(\"repo v%d requires kubo >= v%d; upgrade the binary instead of downgrading\", ver, ver)\n}\nerr = migrations.RunHybridMigrations(ctx, 15, ipfsPath, true)","handlingStrategy":"validation","validationCode":"ver, err := migrations.RepoVersion(ipfsPath)\nif err != nil {\n\treturn err\n}\nif ver > 16 && !allowDowngrade {\n\treturn fmt.Errorf(\"repo v%d is newer than binary target v16; refusing downgrade (set allowDowngrade deliberately)\", ver)\n}\n","typeGuard":"func isDowngradePhaseFailure(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"downgrade phase failed\")\n}\n","tryCatchPattern":"if err := migrations.RunHybridMigrations(ctx, targetVer, ipfsPath, true); err != nil {\n\tif strings.Contains(err.Error(), \"embedded downgrade phase failed\") {\n\t\treturn fmt.Errorf(\"downgrade aborted mid-step; repo may be at an intermediate version — restore backup or re-run: %w\", err)\n\t}\n\treturn err\n}\n","preventionTips":["Prefer matching the binary version to the repo instead of downgrading the repo","Always back up the repo before any downgrade","Check <ipfsDir>/version before and after to know the exact state","Export pins/IPNS keys before downgrading across schema changes"],"tags":["go","migrations","downgrade","embedded"],"backgroundTag":"repo-downgrade-failed","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"}