Suggest newer kernel version in error when no compatible variant exists for current version

[moon-bot-app]

Problem

When get_kernel (or load_kernel) can't find a build variant compatible with the current system, the error message only reports that no matching variant exists for the resolved revision:

Cannot find a build variant for this system in {repo_id} (revision: {revision})

(raised in kernels/src/kernels/utils.py)

This is misleading when the user is on an older version branch of the kernel. For example, a user pinned to (or resolving to) an older version may conclude the kernel doesn't support their setup — e.g. "this kernel has no Torch 2.13 build" — when in fact a newer version branch does have a compatible variant. There is no hint that upgrading the kernel version would fix the problem.

Proposal

When variant resolution fails (no matching variant for the current environment):

1. Enumerate the available version branches for the kernel repo (via _get_available_versions in kernels/src/kernels/_versions.py, which lists the v<N> refs — newer versions first).
2. Check whether any newer version has a variant compatible with the current system (resolve_variant(s) against that revision).
3. If a newer compatible version exists, extend the error message to suggest it, e.g.:

Cannot find a build variant for this system in {repo_id} (revision: v3):

<existing variants trace>

However, version v5 of '{repo_id}' has a build compatible with your system (torch 2.13, cuda 12.8, ...). Consider upgrading to that version.

Considerations

• The check requires resolving variants of newer versions, which may involve extra Hub API calls — acceptable on the error path, but should be best-effort (don't mask the original error if the check itself fails, e.g. offline mode).
• In offline mode (HF_HUB_OFFLINE), the cached-version path (_get_available_versions_from_cache) could be used, or the check skipped gracefully.

---

Requested by Daniël de Kok - Slack thread - Agent trace

[LibertychaserUS]

Thanks for the clear feature request — I had opened #764 before reading the vouch / “issue first” policy; it was auto-closed as expected.

Proposed approach (happy to adjust before any re-open):

• On the no-compatible-variant error path in install.py, best-effort scan newer v<N> revisions (newer-first, stop at first compatible, cap 16).
• If one is compatible, append an upgrade suggestion to the existing error (do not auto-switch).
• Hub/offline failures never replace the original no-variant error.
• Unit tests with mocks (no live Hub).

Local verify: uv run pytest tests/test_upgrade_hint.py -q → 10 passed on branch contrib/kernels-744.

Please ACK if this matches intent (or say what to change). Once vouched / approved, I can re-open the PR.

Assisted-by: Cursor Agent