**PD-ENG-004 `EngTimedOut`.** Every engine command shares one watchdog, and when it fired the run reported PD-INT-001 — "PipDock hit an internal error" — for an sdist build that was simply still compiling, and in the batch phase that error aborted the whole run with no summary and no per-package retry. A timeout is a fact about the engine, not a PipDock bug, so it gets its own code. Raised by PipDock, never classified from stderr, so it joins the `internally_raised` table of the corpus gate. The exec layer starts producing it in the next commit. The nine places: the catalog variant (`as_str`, `area`, `ALL`), both count tests (34 → 35), the corpus gate, both `errors.json` catalogues, `codes.json` and `generated.ts` (regenerated, not edited), the ERROR-CATALOG row (31 → 32 rows), and the five schema goldens that embed `Code` — `Code`, `StepResult`, `ExecutionSummary`, `HealthReport`, `AuditReport` — each re-blessed for exactly one new `const`, which is the contract change this is. **WinError needles include the closing bracket.** Python prints `[WinError N]`, and the bare "winerror 5" also matched 50, 53 and 59: `[WinError 53] The network path was not found` came out as PD-PRM-001, "use a venv". `[WinError 53]` and `[WinError 10013]` (a firewall refusing the socket, raised *as* a PermissionError) now classify as network failures, ahead of the permission rules that would otherwise take them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.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-ENG-004 | Raised by PipDock — an engine command ran past its watchdog (install 30 min, resolve 10 min, listing and checks 3 min) and was stopped | a very long sdist build, or a hung engine | Retry; install a slow-building package on its own. Before 1.4.0 this surfaced as PD-INT-001 and aborted the whole batch |
| 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-PRM-003 | a target source file is not writable | read-only attribute or ACL on a file ruff --fix would rewrite |
Clear the read-only flag (or fix the permissions) and run the fix again. Raised by PipDock before anything is written, not classified from stderr: ruff can fail to write and still exit 1, which the findings-exit rule accepts as a clean run, so a stderr-matched code would arrive after the fix had reported success. Nothing is changed — the fix refuses as a whole rather than half-rewriting a source tree nothing can restore |
| 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)
- 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, 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.