Skip to content

fix(doctor): fall through a python3 that cannot report its version - #201

Merged
cathrynlavery merged 3 commits into
cathrynlavery:mainfrom
Dev-next-gen:fix/doctor-python3-alias-fallback
Sep 10, 2026
Merged

cathrynlavery merged 3 commits into
cathrynlavery:mainfrom
Dev-next-gen:fix/doctor-python3-alias-fallback

Conversation

@Dev-next-gen

Copy link
Copy Markdown
Contributor

Ran /diagram-design:doctor on a stock Windows 11 machine and got a hard FAIL on a box that has a perfectly good Python 3.12.9 on it:

[FAIL] Python runtime: Could not query version via python3: Python was not found;
run without arguments to install from the Microsoft Store, or disable this shortcut
from Settings > Apps > Advanced app settings > App execution aliases.

Nothing is wrong with the machine. python is real, python3 isn't:

> where python3
C:\Users\me\AppData\Local\Microsoft\WindowsApps\python3.exe   # Store alias stub, exits 9009
> where python
C:\Program Files\Python312\python.exe                         # CPython 3.12.9

Windows enables that App Execution Alias by default, and the python.org installer doesn't create a python3.exe, so this is what a normal Windows install looks like rather than a broken one.

The cause is in probe_python_command() — it takes the first name shutil.which resolves and stops there:

for candidate in ("python3", "python"):
    executable = shutil.which(candidate)
    if executable:
        return candidate, executable

Sitting on PATH isn't evidence of being an interpreter. references/doctor.md already says "Resolve python3 first, then python", which reads like a fallback — it just isn't implemented, so python never gets a turn.

It leaks into the next check too. On that failure check_python_runtime still hands back "python3", so check_playwright goes on to probe the same stub and reports Playwright as missing whether it's installed or not.

What this changes

  • A candidate only wins if it actually answers the version probe. Otherwise the loop moves on to the next name.
  • If nothing answers, it still fails, still names the first candidate it tried, and still carries that command's own stderr — a genuinely missing Python reads exactly as it did before.
  • The probe returns a small PythonProbe instead of a bare tuple, which is what lets check_python_runtime reuse the version it already asked for instead of shelling out a second time.
  • Wrote the fallback into references/doctor.md so the contract and the code say the same thing.

Tests

Three cases in scripts/test-verify-doctor.py: a python3 that can't report its version, nothing runnable at all, and an empty PATH. They stub shutil.which and run_command, so they don't depend on what the runner happens to have installed. Against the current code the first one fails with the exact symptom above:

AssertionError: expected (pass, contains 'Python 3.12.9 found via python');
got (fail, 'Could not query version via python3: Python was not found; run without
arguments to install from the Microsoft Store...')

Probably worth saying why CI didn't catch this: the Windows leg does run, but setup-python puts a working python3 on PATH, so the runner never looks like an ordinary Windows desktop.

Verified

Full CONTRIBUTING gate list passes on Windows / Python 3.12. I couldn't run lint-render.py, the README thumbnails or claude plugin validate locally (Playwright, Pillow, npx) — none of them touch this path.

Doctor on the same machine, after the change:

[PASS] Python runtime: Python 3.12.9 found via python at C:\Program Files\Python312\python.EXE.

No manifest versions touched.

#190 also touches verify-doctor.py, but not this function, so the two should sit fine next to each other.

@greptile-apps

greptile-apps Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 4/5

The process-launch exception path should be handled before merging because a newly reached fallback candidate can crash the doctor.

Findings

  1. P1 Launch errors bypass fallback ▶

Summary

  • Introduces a structured PythonProbe result and reuses the captured version.
  • Adds tests for Windows Store aliases, total probe failure, and an empty PATH.
  • Documents the executable-validation fallback behavior.

Comment thread scripts/verify-doctor.py Resolved
Dev-next-gen and others added 2 commits September 9, 2026 05:39
The python3 fallback only survived an interpreter that exits non-zero. A
name on PATH that cannot be spawned at all -- an App Execution Alias for an
uninstalled app, a dangling symlink, a file without the exec bit -- raised
out of run_command and ended the run with a traceback, on the very
candidate the fallback exists to survive.

Catch OSError in run_command and return it as a non-zero result. Every
caller already asks only whether the command answered, so the probe loop
falls through as it does for any other dud, and check_playwright, which is
handed the command name even when the runtime check failed, warns instead
of dying.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_018yueXNv7ew2s8sHhv43HG4
@cathrynlavery
cathrynlavery merged commit 3a1a7e0 into cathrynlavery:main Sep 10, 2026
8 checks passed
@Dev-next-gen
Dev-next-gen deleted the fix/doctor-python3-alias-fallback branch September 11, 2026 00:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants