Files
pipdock/docs/ERROR-CATALOG.md
T
poli0981andClaude Opus 5.5 2b4681954b feat(errors): PD-ENG-004 for an engine watchdog; WinError rules match exactly
**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>
2026-10-17 00:55:27 +07:00

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)

  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.