{"record":{"id":"e8e8aba057e1e370","repo":"ipfs/kubo","slug":"could-not-determine-external-migration-paths-w","errorCode":null,"errorMessage":"could not determine external migration paths: %w","messagePattern":"could not determine external migration paths: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":422,"sourceCode":"\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to get migration fetcher: %w\", err)\n\t\t}\n\t\tdefer fetcher.Close()\n\t\treturn RunMigration(ctx, fetcher, targetVer, ipfsDir, allowDowngrade)\n\t}\n\n\t// Case 3: Hybrid migration (current < 16, target ≥ 16)\n\tif needsExternal && needsEmbedded {\n\t\tlogger.Printf(\"Starting hybrid migration from version %d to %d\", currentVer, targetVer)\n\t\tlogger.Print(\"Using hybrid migration strategy: external to v16, then embedded\")\n\n\t\t// Phase 1: Use external migrations to get to v16\n\t\tlogger.Printf(\"Phase 1: External migration from v%d to v%d\", currentVer, embeddedMigrationsMinVersion)\n\n\t\t// Check for external migration binaries in PATH first\n\t\tmigrations, binPaths, err := findMigrations(ctx, currentVer, embeddedMigrationsMinVersion)\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\n\t\t\t}\n\t\t}\n\n\t\tif foundAll {\n\t\t\tif err = runMigrationsFromPath(ctx, migrations, binPaths, ipfsDir, logger, false); err != nil {\n\t\t\t\treturn fmt.Errorf(\"external migration phase failed: %w\", err)\n\t\t\t}\n\t\t} else {\n\t\t\tmigrationCfg, err := ReadMigrationConfig(ipfsDir, \"\")\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"could not read migration config: %w\", err)","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L404-L440","documentation":"In the hybrid path (current < 16, target >= 16), phase 1 uses external migration binaries to reach v16. RunHybridMigrations wraps any findMigrations failure during this phase with this message, distinguishing it from the pure-external case.","triggerScenarios":"findMigrations(ctx, currentVer, 16) errors while resolving binaries for the first phase — e.g. invalid version inputs, errors scanning PATH/migrations directory, or context cancellation.","commonSituations":"Upgrading very old repos (e.g. v9) to a modern kubo on machines without fs-repo-migrations installed; broken PATH in systemd unit files; permission issues on the migrations directory.","solutions":["Install fs-repo-migrations and ensure its binaries are on PATH for the daemon's environment","Check systemd service Environment/PATH if running under systemd — PATH there is minimal","Pre-download phase-1 migration binaries into the repo's migrations directory","Read the wrapped inner error for the precise lookup failure"],"exampleFix":"# before: systemd unit with no PATH to migration binaries\nExecStart=/usr/local/bin/ipfs daemon --migrate\n# after\n[Service]\nEnvironment=PATH=/usr/local/bin:/usr/bin:/root/go/bin\nExecStart=/usr/local/bin/ipfs daemon --migrate","handlingStrategy":"fallback","validationCode":"mig, paths, err := migration.FindMigrations(ctx, cur, 16)\nif err != nil || len(paths) < len(mig) {\n    log.Println(\"phase-1 external binaries missing; install fs-repo-migrations\")\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"could not determine external migration paths\") {\n    return fmt.Errorf(\"install fs-repo-migrations (PATH or migrations dir) for the v%d->v16 phase: %w\", cur, err)\n}","preventionTips":["For upgrades from very old repos, install fs-repo-migrations first","Fix daemon PATH (systemd units often have minimal PATH)","Pre-place phase-1 binaries in the repo migrations directory","Dry-run the hybrid migration on a copy of the repo"],"tags":["migrations","hybrid","path-lookup"],"backgroundTag":"migration-binaries-not-found","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"}