goharbor/harbor · critical · MigratioNotFound

no migration path found to target version

Error message

no migration path found to target version

What it means

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.

Source

Thrown at make/photon/prepare/utils/migration.py:66

        list: the module of migrations in the upgrade path
    """
    upgrade_path = []
    next_version, visited, q = {}, set(), deque()
    q.append(target_version)
    found = False
    while q: # BFS to find a valid path
        version = MigrationVersion(q.popleft())
        visited.add(version.name)
        if version.name == input_version:
            found = True
            break # break loop cause migration path found
        for v in version.down_versions:
            next_version[v] = version.name
            if v not in (visited.union(q)):
                q.append(v)

    if not found:
        raise MigratioNotFound('no migration path found to target version')

    current_version = MigrationVersion(input_version)
    while current_version.name != target_version:
        current_version = MigrationVersion(next_version[current_version.name])
        upgrade_path.append(current_version)
    return list(map(lambda x: x.module, upgrade_path))

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. 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
2. For pre-1.8.0 installs, first upgrade to 1.8.x using the legacy migration flow (harbor-migrator v1.8), then continue stepwise
3. Upgrade through intermediate supported releases rather than one giant jump (e.g. 1.10 -> 2.x -> latest)
4. If on a dev/fork build, upgrade to the nearest official release with a real version number first
5. Restore any deleted migrations/version_* modules and verify each down_revisions entry exists

Example fix

# before (hypothetical jump)
$ docker run goharbor/prepare:migrator /harbor-migrator migrate -i 1.7.5 -t 2.9.0
MigratioNotFound: no migration path found to target version

# after (stepwise, supported path)
$ ls make/photon/prepare/migrations/ | sort   # confirm 1_8_0 exists
# 1.7.5 -> upgrade to 1.8.x with the v1.8 harbor-migrator first
# then 1.8.x -> target via current migrator

import importlib
# verify reachability before calling migration.search()
def path_exists(input_version, target_version, versions):
    seen, stack = set(), [target_version]
    while stack:
        v = stack.pop()
        if v == input_version:
            return True
        if v in seen:
            continue
        seen.add(v)
        stack.extend(importlib.import_module(
            'migrations.version_{}'.format(v.replace('.', '_'))).down_revisions)
    return False

from utils import migration
try:
    mods = migration.search(input_version, target_version)
except migration.MigratioNotFound:
    # fallback: upgrade stepwise through the nearest ancestor release
    step = nearest_reachable_release(input_version)
    run_upgrade(input_version, step)
    run_upgrade(step, target_version)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• File {} not exist
• invalid {}
• key file {} permission is not 600
• File {} should readable by owner
• cert file {} should include SAN

AI-assisted analysis of goharbor/harbor@7b2fd08cc5 (2026-08-16). Data as JSON: /api/errors/73b64c9fb1b0924d. Report an issue: GitHub.