The architectural centre of S3. `UpdateFlow` is a **resumable state machine** and IPC is stateless: `plan_resolve` builds the flow, the user reads the preview, and `plan_decide` or `plan_execute` arrives as a separate message seconds later. Something has to hold the flow in between, and that is `PlanSlot` in `AppState`. **One plan at a time, and `PD-RES-003` when a second arrives.** Nothing structurally prevents it — the calls are independent messages — and two concurrent plans would interleave engine commands against one environment while DATA-FLOW §9.3's staleness check compared against a set the other plan was busy changing. `claim()` takes the slot before any work, and **every** exit path releases it: a claim that leaks would leave the session refusing plans forever, which is the failure mode this design has to be careful about. `Busy` moves the flow out rather than borrowing it, because `execute` awaits for as long as the install takes and holding the slot's lock across that would block `plan_cancel` — the one command that must work precisely then. For the same reason the cancellation token lives in its own lock, held only long enough to read an `Option`. **`UpdateFlow::start` now takes the pins, not the `Store`.** Not a tidy-up: `Store` wraps a `rusqlite::Connection` and is `Send` but not `Sync`, so a future holding `&Store` across an await is not `Send` and a Tauri command cannot return one. It did not compile. Reading the pins first is one synchronous line at each call site, and the flow no longer reaches into a database at all — it can now be driven in a test without one. `plan_execute` returns the snapshot alongside the summary. The CLI prints the id *before* execution because DATA-FLOW §3 draws them as distinct states; the summary sheet needs it *after*, to offer the rollback. One envelope beats a second command to go and look it up. `PD-RES-003` went through the whole catalog process rather than round it: the "no code without a fixture" gate rejected it until it was listed as internally raised with the module that owns it, and both locale catalogs carry its copy — otherwise `PdErrorRow` would show `errors.unknown` for a condition PipDock raises itself. `Decision` joins SCHEMA_TYPES too, since `PdConflictRow` needs the 3-way type. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.8 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-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.