Requires-Python is now enforced by PipDock, not by the engine. SP-2 found the engines disagree: scipy 1.7.3 declares >=3.7,<3.11, and on Python 3.12 pip refuses it while uv plans to install it. G5 promises one behaviour across heads, so the preview must not change shape because the user flipped the engine radio. crates/pipdock-core/src/compat.rs screens every candidate against the environment's version before any engine command runs; rejects surface as PD-PKG-001 with the required range shown against the found version. This does not weaken "explain, don't reimplement" — resolution stays entirely the engine's. compat.rs only filters candidates the engine should never have been offered, using the slice of PEP 440 that actually appears in Requires-Python: comparison, wildcard and compatible-release operators. Specifiers it cannot parse count as compatible, because PipDock failing to read metadata must never be the reason an installable package is refused. Nine tests, including the exact scipy case the spike captured and the boundary cases where an off-by-one would reject a supported Python. probe.py keeps -I, and the cost is disclosed rather than hidden. Isolated mode is what stops a poisoned environment injecting code into the probe, so it stays; dropping to -E was rejected because a package in user site is part of the untrusted surface the isolation exists to exclude, and probing twice was rejected as a second interpreter start per scan for a non-primary case. Instead probe.py now reports hidden_user_site — the user-site path when it exists, sits off sys.path and is non-empty, else null. Verified: the system Python reports the path (352 dists), a venv reports null. The Installed screen shows a note naming the path only when it is non-null, so users of the affected case are told exactly what is missing while everyone else sees nothing. ERROR-CATALOG PD-PKG-001 changes from a stderr classification to a PipDock-raised code, because engine stderr cannot support it: pip reports it as plain "No matching distribution found", indistinguishable from PD-PKG-002, and uv does not enforce it at all. Docs updated: ARCHITECTURE 3 and 4, DATA-FLOW 2, SECURITY 2, UI-SPEC 4, ERROR-CATALOG 2, ROADMAP, CLAUDE.md, spikes/README.md. EN and VI strings added for both notes. Two non-blocking questions remain in spikes/README.md: search-ranking scope for M1, and how to obtain the five error fixtures this machine cannot produce. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.7 KiB
PipDock — Error Catalog
Version 0.1 · 2026-07-17. Single source of truth: crates/pipdock-core/src/errors/catalog.rs. Every user-visible failure carries exactly one code; classifiers run over engine stderr in priority order (first match wins), falling back to PD-ENG-999.
1. Code space
PD-<AREA>-<NNN> — areas: ENV environment, ENG engine, RES resolution, BLD build, PKG package/index, NET network, PRM permissions, SNP snapshot, SYS system, HLT health, INT internal.
2. Catalog (v1 launch set)
| Code | Detection (stderr/context pattern) | Cause | User action (EN; VI mirrored in locale files) |
|---|---|---|---|
| PD-ENV-001 | interpreter path missing/not executable | env deleted or moved | Re-scan environments; remove stale entry |
| PD-ENV-002 | externally-managed-environment / EXTERNALLY-MANAGED marker |
PEP 668 protected Python | Use a virtual env; system override only via Settings (discouraged) |
| PD-ENV-003 | probe.py non-zero / unparseable | broken env metadata | Open logs; recreate the venv |
| PD-ENG-001 | engine binary not found | pip/uv missing | Install engine or switch engine in Settings |
| PD-ENG-002 | pip < 22.2 with plan requested | no --dry-run --report |
One-click "Upgrade pip" then retry |
| PD-ENG-003 | uv output shape unrecognized | uv newer than adapter | Update PipDock; temporarily switch engine to pip |
| PD-RES-001 | ResolutionImpossible / uv equivalent |
constraints cannot be satisfied | Per-package Skip/Force choices in the preview |
| PD-RES-002 | plan stale (>10 min) or env drift hash mismatch | env changed since preview | Re-run preview |
| PD-BLD-001 | Microsoft Visual C++ 14.0 or greater is required |
missing MSVC build tools | Install VS Build Tools, or prefer a wheel-providing version |
| PD-BLD-002 | error in pyproject.toml / Backend … failed / metadata-generation-failed |
broken sdist build backend | Try previous version; report upstream (owner's example case) |
| PD-BLD-003 | error: Microsoft Visual C++-absent + Failed building wheel generic |
sdist-only build failed | Same as above; details in log |
| PD-PKG-001 | Raised by PipDock before the engine runs — crates/pipdock-core/src/compat.rs evaluates the candidate's Requires-Python against the env's version. (Engine stderr is not a reliable signal: pip reports it as plain No matching distribution found, indistinguishable from PD-PKG-002, and uv does not enforce it at all.) |
package needs different Python | Shows required range vs env version |
| PD-PKG-002 | No matching distribution found (plain) |
name/version typo or yanked | Check spelling/version; pipdock info <pkg> |
| PD-PKG-003 | File was already yanked / yanked marker |
yanked release requested | Pick a non-yanked version |
| PD-PKG-004 | hash mismatch / THESE PACKAGES DO NOT MATCH THE HASHES |
corrupted download | Purge engine cache (P1 UI; CLI: engine cache purge) and retry |
| PD-NET-001 | timeout / Connection aborted / DNS failure |
offline or PyPI unreachable | Offline banner; retry; search stays local |
| PD-NET-002 | TLS/SSL verification failure | proxy/AV interception | Corporate proxy note; never suggests disabling verification |
| PD-NET-010 | index refresh failed | PEP 691 fetch error | Retry later; stale index still searchable (staleness shown) |
| PD-NET-011 | tools venv bootstrap fetch failed | offline during Health setup | Health disabled until online |
| PD-PRM-001 | PermissionError writing site-packages |
admin-owned Python (Program Files) | v1 blocks: use a venv (elevation is P2-3) |
| PD-PRM-002 | file lock (WinError 32) |
package in use by a running process | Close Python processes using the env; retry |
| PD-SNP-001 | snapshot write failed pre-execution | disk/permission issue on app data | Plan aborted, nothing executed; free space / check AV |
| PD-SNP-002 | rollback target release unavailable on PyPI | deleted/yanked upstream | Partial rollback offered; affected pins listed |
| PD-SYS-001 | path too long patterns |
MAX_PATH without long-path opt-in | Enable Windows long paths (help link) |
| PD-SYS-002 | disk full (No space left/WinError 112) |
storage | Free space |
| PD-HLT-001..003 | tool missing / non-zero / watchdog timeout | tools venv issue | Re-sync tools env; partial report shown |
| PD-INT-001 | panic/unexpected | PipDock bug | Report-bug deep link prefilled |
| PD-ENG-999 | unclassified engine failure | unknown | stderr tail shown; report-bug encouraged (feeds catalog growth) |
Classifier hygiene: patterns live beside unit tests with captured real stderr fixtures (collected in spike SP-2 and grown from bug reports); a fixture must exist for every code before it ships.
3. Presentation rules
GUI: code · localized one-liner · [Details ⌄ stderr tail ≤ 40 lines] · [Copy full log] · [Report bug]. CLI: error[PD-XXX-NNN]: <one-liner> on stderr; --json embeds {code, reason, stderrTail}. Localization: only the one-liner and action text are localized; codes and stderr never are.
4. Bug-report pipeline (owner requirement: console error attached to template)
- App keeps a per-plan ring buffer (last 64 KB) of engine stdout/stderr plus the app log tail.
- Report bug builds a prefilled GitHub new-issue URL against
.github/ISSUE_TEMPLATE/bug_report.yml:https://github.com/poli0981/pipdock/issues/new?template=bug_report.yml&pd-version=…&os=…&engine=…&python=…&error-code=…&log-excerpt=… - URL budget: GitHub rejects very long URLs, so
log-excerptis truncated to ≈ 6 000 characters (tail-biased); the full log is simultaneously copied to the clipboard and the dialog says so ("paste into the issue if asked"). - Nothing is ever sent automatically — the user reviews the issue form in their browser. This is the entire "telemetry" story.