Files
pipdock/docs/ERROR-CATALOG.md
T
poli0981andClaude Opus 5 1748ea06f5 feat(errors): PD-HLT-004, for a Python that cannot make a venv
`python -m venv` spawning fine and exiting non-zero had no honest code. The tools venv
bootstrap (next commit) is the first thing that can hit it, so the code lands before the
error path that raises it rather than being retrofitted onto one.

None of the three candidates worked. PD-NET-011 is Area::Net, and run::exit_for derives
the exit code from the area — so `tools sync || wait-for-network && retry` would loop
forever on a stripped Python, and both locales' shipped copy is explicitly about
downloading. PD-HLT-001 tells the user to re-sync the tools environment, which is the
operation that just failed. PD-INT-001 is "a PipDock bug", and a Python built without the
venv module is not one. Area::Hlt already maps to exit 1, which is right.

All eight places from CLAUDE.md in one commit, because seven of them are a broken build:
the variant, Code::ALL, both count assertions (32 -> 33), classifier_corpus's
internally_raised table without which the no-code-without-a-fixture gate fails, en+vi copy
under the 90-char cap, regenerated codes.json and bindings, and the catalog doc. Three
goldens re-blessed — Code plus the two schemas that embed it, StepResult and
ExecutionSummary. ResolutionReport does not embed it and did not move.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 21:31:22 +07:00

7.0 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-RES-003 a plan is already resolving or executing another plan is in flight in this session Wait for it, or cancel it
PD-RES-004 Raised by PipDock before the engine runs — the reverse-dependency guard (DATA-FLOW §5) found installed dependents and execution was attempted without the user accepting the breakage removing these packages would break others Remove the dependents too, or force the removal knowingly
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..004 tool missing / non-zero / watchdog timeout / venv creation failed tools venv issue Re-sync tools env; partial report shown. PD-HLT-004 is raised by PipDock, not classified from stderr — python -m venv exited non-zero, so the fix is the interpreter, not another re-sync
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, and the row says so beside the button rather than leaving the user to guess what "Report bug" does.

Built in pipdock_core::report and called by both heads, so pipdock self report-bug and the GUI's report_bug_url cannot drift apart the day the template gains a field. The GUI's ring buffer is fed from three places, not one: the plan-progress forwarder, and plan_resolve's success and failure paths — a resolve emits no progress events at all, and a plan that would not resolve is the commonest thing anyone reports. The CLI has no ring until M3's logging subsystem, so its excerpt is empty and the URL simply omits the parameter.