Files
pipdock/docs/ERROR-CATALOG.md
T
poli0981andClaude Opus 5 4ab948ac7b feat: implement the two owner decisions from spike week
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>
2026-07-27 18:38:46 +07:00

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)

  1. App keeps a per-plan ring buffer (last 64 KB) of engine stdout/stderr plus the app log tail.
  2. 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=…
  3. URL budget: GitHub rejects very long URLs, so log-excerpt is 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").
  4. Nothing is ever sent automatically — the user reviews the issue form in their browser. This is the entire "telemetry" story.