{"record":{"id":"63b34a4b09303db8","repo":"ipfs/kubo","slug":"migration-s-failed-w","errorCode":null,"errorMessage":"migration %s failed: %w","messagePattern":"migration (.+?) failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":94,"sourceCode":"\t\tif err != nil {\n\t\t\tlogger.Print(\"Failed to download migrations.\")\n\t\t\treturn err\n\t\t}\n\n\t\tfor i := range missing {\n\t\t\tbinPaths[missing[i]] = fetched[i]\n\t\t}\n\t}\n\n\tvar revert bool\n\tif fromVer > targetVer {\n\t\trevert = true\n\t}\n\tfor _, migration := range migrations {\n\t\tlogger.Println(\"Running migration\", migration, \"...\")\n\t\terr = runMigration(ctx, binPaths[migration], ipfsDir, revert, logger)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"migration %s failed: %w\", migration, err)\n\t\t}\n\t}\n\tlogger.Printf(\"Success: fs-repo migrated to version %d.\\n\", targetVer)\n\n\treturn nil\n}\n\nfunc NeedMigration(target int) (bool, error) {\n\tvnum, err := RepoVersion(\"\")\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"could not get repo version: %w\", err)\n\t}\n\n\treturn vnum != target, nil\n}\n\nfunc ExeName(name string) string {\n\tif runtime.GOOS == \"windows\" {","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L76-L112","documentation":"RunMigration executed one of the fetched/bundled fs-repo migration binaries and it exited with an error; the message names which migration step failed and wraps its output. The repo may be mid-migration, so a backup matters.","triggerScenarios":"runMigration executes the migration binary for a version step and it returns non-zero: bad flags, missing repo lock, corrupted data, insufficient disk space, or the binary itself crashed.","commonSituations":"Interrupted previous migration leaving the repo half-converted; running as a different user than the repo owner so the migration cannot write; daemon still running and holding the repo lock; out-of-space disk during migration.","solutions":["Read the wrapped underlying error and the migration binary's output to identify the failing step.","Stop any running ipfs daemon so the repo is not locked, then retry.","Ensure adequate disk space and correct ownership/permissions on the repo directory.","Restore the repo from the backup taken before migration and retry the migration cleanly."],"exampleFix":"// before\n# run migration while daemon is running -> fails\n// after\nipfs shutdown  # or kill daemon\nfs-repo-migrations","handlingStrategy":"try-catch","validationCode":"// ensure no daemon holds the lock and enough disk space\nif out, err := exec.Command(\"pgrep\", \"-f\", \"ipfs daemon\").Output(); err == nil {\n    return errors.New(\"stop the ipfs daemon before migrating\")\n}","typeGuard":null,"tryCatchPattern":"if err := RunMigration(ctx, cfg, ipfsDir, from, to, false); err != nil {\n    var exitErr *exec.ExitError\n    if errors.As(err, &exitErr) {\n        log.Printf(\"migration binary failed: %v\", err) // inspect wrapped cause\n    }\n}","preventionTips":["Shut down the daemon before migrating","Ensure sufficient disk space and repo ownership","Take a full repo backup before starting migrations"],"tags":["migrations","process-execution","go"],"backgroundTag":"migration-binary-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"}