{"record":{"id":"6f7fdb77c3070b2f","repo":"ipfs/kubo","slug":"could-not-determine-migration-paths-w","errorCode":null,"errorMessage":"could not determine migration paths: %w","messagePattern":"could not determine migration paths: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/fsrepo/migrations/migrations.go","lineNumber":381,"sourceCode":"\t// Determine migration strategy based on version ranges\n\tneedsExternal := currentVer < embeddedMigrationsMinVersion\n\tneedsEmbedded := targetVer >= embeddedMigrationsMinVersion\n\n\t// Case 1: Pure embedded migration (both current and target ≥ 16)\n\tif !needsExternal && needsEmbedded {\n\t\treturn RunEmbeddedMigrations(ctx, targetVer, ipfsDir, allowDowngrade)\n\t}\n\n\t// For cases requiring external migrations, we check if migration binaries\n\t// are available in PATH before attempting network downloads\n\n\t// Case 2: Pure external migration (target < 16)\n\tif needsExternal && !needsEmbedded {\n\n\t\t// Check for migration binaries in PATH first (for testing/local development)\n\t\tmigrations, binPaths, err := findMigrations(ctx, currentVer, targetVer)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"could not determine 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\treturn runMigrationsFromPath(ctx, migrations, binPaths, ipfsDir, logger, false)\n\t\t}\n\n\t\t// Fall back to network download (original behavior)\n\t\tmigrationCfg, err := ReadMigrationConfig(ipfsDir, \"\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"could not read migration config: %w\", err)","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/repo/fsrepo/migrations/migrations.go#L363-L399","documentation":"For a purely external migration (target < 16), RunHybridMigrations calls findMigrations to enumerate required fs-repo-migration binaries (checking PATH and the migrations dir). If that lookup itself fails, the error is wrapped with this message.","triggerScenarios":"findMigrations returns an error while resolving migration names for currentVer→targetVer, e.g. an invalid version pair, failures listing the migrations directory, or context cancellation during lookup.","commonSituations":"Very old repos (pre-v10) requiring many migration binaries; unusual IPFS_PATH permissions; context timeouts during daemon startup.","solutions":["Inspect the wrapped inner error for the actual cause","Install fs-repo-migrations so binaries are discoverable in PATH","Pre-download the needed migration binaries into IPFS_PATH's migrations directory","Re-run with a longer-lived context and correct repo path"],"exampleFix":"// before\nipfs daemon --migrate  # fails: could not determine migration paths\n// after\ngo install github.com/ipfs/fs-repo-migrations/fs-repo-migrations@latest\nexport PATH=\"$PATH:$(go env GOPATH)/bin\"\nipfs daemon --migrate","handlingStrategy":"validation","validationCode":"mig, paths, err := migration.FindMigrations(ctx, cur, target) // or check manually\nif err != nil || len(paths) < len(mig) {\n    log.Println(\"install fs-repo-migrations or pre-download binaries\")\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"could not determine migration paths\") {\n    return fmt.Errorf(\"install fs-repo-migrations in PATH: %w\", err)\n}","preventionTips":["Install fs-repo-migrations wherever the daemon runs","Ensure PATH includes the migration binaries in daemon environments (systemd, Docker)","Pre-download needed binaries into the repo migrations dir","Test the migration path in staging before production upgrades"],"tags":["migrations","path-lookup","binaries"],"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"}