{"record":{"id":"73b64c9fb1b0924d","repo":"goharbor/harbor","slug":"no-migration-path-found-to-target-version","errorCode":null,"errorMessage":"no migration path found to target version","messagePattern":"no migration path found to target version","errorType":"exception","errorClass":"MigratioNotFound","httpStatus":null,"severity":"critical","filePath":"make/photon/prepare/utils/migration.py","lineNumber":66,"sourceCode":"        list: the module of migrations in the upgrade path\n    \"\"\"\n    upgrade_path = []\n    next_version, visited, q = {}, set(), deque()\n    q.append(target_version)\n    found = False\n    while q: # BFS to find a valid path\n        version = MigrationVersion(q.popleft())\n        visited.add(version.name)\n        if version.name == input_version:\n            found = True\n            break # break loop cause migration path found\n        for v in version.down_versions:\n            next_version[v] = version.name\n            if v not in (visited.union(q)):\n                q.append(v)\n\n    if not found:\n        raise MigratioNotFound('no migration path found to target version')\n\n    current_version = MigrationVersion(input_version)\n    while current_version.name != target_version:\n        current_version = MigrationVersion(next_version[current_version.name])\n        upgrade_path.append(current_version)\n    return list(map(lambda x: x.module, upgrade_path))","sourceCodeStart":48,"sourceCodeEnd":72,"githubUrl":"https://github.com/goharbor/harbor/blob/7b2fd08cc568955cca339afeefab27372840d936/make/photon/prepare/utils/migration.py#L48-L72","documentation":"Thrown by search() in make/photon/prepare/utils/migration.py (class MigratioNotFound) when the BFS over make/photon/prepare/migrations/version_* modules cannot reach your current (input) version starting from the target version by following each module's down_revisions chain. It means the installed Harbor version is not an ancestor of the version you are upgrading to - because it is older than the oldest supported migration, is a custom/dev version string with no module, or the chain is broken by deleted/edited migration files.","triggerScenarios":"Running Harbor's migration (migrator/upgrader invoking migration.search(input_version, target_version)) when input_version names a version with no migrations/version_X module (e.g. pre-1.8.0 harbor.cfg installs, '2.9.0-dev', a fork's version), or when someone removed/renamed migration modules so the down_revisions chain skips the input version.","commonSituations":"Upgrading very old Harbor installs (<1.8.0) directly to a modern release; upgrading dev builds or forks whose version strings never had migration modules; users who deleted migration directories to slim images; skipping major versions whose chain was later reworked.","solutions":["Check that your current version has a module: ls make/photon/prepare/migrations/ (or inside the migrator image) - there must be a version_<input> directory","For pre-1.8.0 installs, first upgrade to 1.8.x using the legacy migration flow (harbor-migrator v1.8), then continue stepwise","Upgrade through intermediate supported releases rather than one giant jump (e.g. 1.10 -> 2.x -> latest)","If on a dev/fork build, upgrade to the nearest official release with a real version number first","Restore any deleted migrations/version_* modules and verify each down_revisions entry exists"],"exampleFix":"# before (hypothetical jump)\n$ docker run goharbor/prepare:migrator /harbor-migrator migrate -i 1.7.5 -t 2.9.0\nMigratioNotFound: no migration path found to target version\n\n# after (stepwise, supported path)\n$ ls make/photon/prepare/migrations/ | sort   # confirm 1_8_0 exists\n# 1.7.5 -> upgrade to 1.8.x with the v1.8 harbor-migrator first\n# then 1.8.x -> target via current migrator","handlingStrategy":"fallback","validationCode":"import importlib\n# verify reachability before calling migration.search()\ndef path_exists(input_version, target_version, versions):\n    seen, stack = set(), [target_version]\n    while stack:\n        v = stack.pop()\n        if v == input_version:\n            return True\n        if v in seen:\n            continue\n        seen.add(v)\n        stack.extend(importlib.import_module(\n            'migrations.version_{}'.format(v.replace('.', '_'))).down_revisions)\n    return False","typeGuard":null,"tryCatchPattern":"from utils import migration\ntry:\n    mods = migration.search(input_version, target_version)\nexcept migration.MigratioNotFound:\n    # fallback: upgrade stepwise through the nearest ancestor release\n    step = nearest_reachable_release(input_version)\n    run_upgrade(input_version, step)\n    run_upgrade(step, target_version)","preventionTips":["Always upgrade through officially released versions, not dev builds","Never delete migrations/version_* modules from the prepare/migrator image","Pre-1.8.0 installations require the legacy 1.8 migrator before the modern one","Dry-run the migrator in a cloned environment before touching production data"],"tags":["harbor","migration","upgrade","versioning"],"backgroundTag":null,"analyzedSha":"7b2fd08cc568955cca339afeefab27372840d936","analyzedAt":"2026-08-16T00:00:10.961Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}