{"record":{"id":"5caeb6bce0759d86","repo":"ipfs/kubo","slug":"fs-repo-requires-migration","errorCode":null,"errorMessage":"fs-repo requires migration","messagePattern":"fs-repo requires migration","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/ipfs/kubo/daemon.go","lineNumber":358,"sourceCode":"\n\t\t// Get current repo version for more informative message\n\t\tcurrentVersion, verErr := migrations.RepoVersion(cctx.ConfigRoot)\n\t\tif verErr != nil {\n\t\t\t// Fallback to generic message if we can't read version\n\t\t\tfmt.Printf(\"Kubo repository at %s requires migration.\\n\", cctx.ConfigRoot)\n\t\t} else {\n\t\t\tfmt.Printf(\"Kubo repository at %s has version %d and needs to be migrated to version %d.\\n\",\n\t\t\t\tcctx.ConfigRoot, currentVersion, version.RepoVersion)\n\t\t}\n\n\t\tif !found {\n\t\t\tdomigrate = YesNoPrompt(\"Run migrations now? [y/N]\")\n\t\t}\n\t\tclose(migrationDone)\n\n\t\tif !domigrate {\n\t\t\tfmt.Printf(\"Not running migrations on repository at %s. Re-run daemon with --migrate or see 'ipfs repo migrate --help'\\n\", cctx.ConfigRoot)\n\t\t\treturn errors.New(\"fs-repo requires migration\")\n\t\t}\n\n\t\t// Use hybrid migration strategy that intelligently combines external and embedded migrations\n\t\t// Use req.Context instead of cctx.Context() to avoid attempting repo open before migrations complete\n\t\terr = migrations.RunHybridMigrations(req.Context, version.RepoVersion, cctx.ConfigRoot, false)\n\t\tif err != nil {\n\t\t\tfmt.Println(\"Repository migration failed:\")\n\t\t\tfmt.Printf(\"  %s\\n\", err)\n\t\t\tfmt.Println(\"If you think this is a bug, please file an issue and include this whole log output.\")\n\t\t\tfmt.Println(\"  https://github.com/ipfs/kubo\")\n\t\t\treturn err\n\t\t}\n\n\t\t// Note: Migration caching/pinning functionality has been deprecated\n\t\t// The hybrid migration system handles legacy migrations more efficiently\n\n\t\trepo, err = fsrepo.Open(cctx.ConfigRoot)\n\t\tif err != nil {","sourceCodeStart":340,"sourceCodeEnd":376,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/cmd/ipfs/kubo/daemon.go#L340-L376","documentation":"The daemon detected that the fs-repo on disk was written by an older kubo version and requires migrations. Because the user declined (or could not confirm) running them now, the daemon refuses to start and returns this error to signal the repo version gap.","triggerScenarios":"Starting `ipfs daemon` on an IPFS_PATH whose repo version is lower than version.RepoVersion, and answering 'n' to 'Run migrations now?' (or running without --migrate in a non-interactive context where the prompt resolves to no).","commonSituations":"Upgrading the kubo binary across a repo-version boundary without migrating; running the daemon non-interactively (scripts, containers, systemd) where the y/N prompt defaults to no; sharing one IPFS_PATH between kubo versions.","solutions":["Run `ipfs daemon --migrate` to apply the migrations automatically before startup","Run migrations explicitly: `ipfs repo migrate` (see `ipfs repo migrate --help`)","In non-interactive environments set the affirmative flag/env for auto-migration instead of relying on the prompt","Pin the previous kubo version if you cannot migrate yet (repo is forward-compatible only)","Back up IPFS_PATH (config + datastore) before migrating"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// compare repo and binary versions before starting the daemon\nout, _ := exec.Command(\"ipfs\", \"repo\", \"version\").Output()\nrepoVer := strings.TrimSpace(string(out))\n_ = repoVer // if lower than the binary's RepoVersion, migrate first","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `ipfs repo migrate` right after upgrading the binary","Use `--migrate` in scripts/containers so the prompt never blocks startup","Back up IPFS_PATH before upgrading","Don't share one IPFS_PATH across different kubo versions"],"tags":["daemon","migrations","repo-version"],"backgroundTag":"fs-repo-requires-migration","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"}