Files
pipdock/docs/ERROR-CATALOG.md
poli0981andClaude Opus 5.5 2539950cd5 fix: what an independent review of 1.6.0 found
A venv made with --symlinks is run and stored as itself, not as the base
Python its python.exe links to: validate_interpreter returned the
canonical path, so `--env .venv update --all --yes` would have changed
the system Python. Canonicalizing now only decides where a link leads
and whether it is PipDock's own; a link to another program is refused,
and a Microsoft Store alias (os error 1920) is judged by its own path.

The GUI merges and removes an added row by its path rather than by
envHash, which follows links: a re-add replaces a broken row, removal
sticks for an entry whose file is gone (a share), and neither runs
during a scan. Added entries are validated again on every listing in
both heads (envs::probe_listed), and the CLI checks its stored default
when it uses it. `env remove` makes a typed path absolute first.

SECURITY section 2 and env_probe's doc claimed an enforcement point over
IPC; they now say what is checked, and backlog X36-b records the rest.
notify.yml reports a Triage failure on a pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00

64 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 — checked before the probe, and since 1.4.0 also a failed spawn of an interpreter that is not there (it read as PD-ENG-001, "install the engine"). Since 1.6.0 also a path a person supplied that `envs::validate_interpreter` refuses: not named like a Python interpreter (or a link to something that is not), or inside PipDock's own tools or audit venv — checked when it is added, again on every listing, and for the CLI's stored default when it is used | env deleted or moved; the wrong file picked | Re-scan environments; remove stale entry — *Remove from list* on an added row (1.6.0), the first time this advice had a button |
| PD-ENV-002 | **Raised by PipDock** on the fresh probe every mutating flow starts with (`flow::preamble`, DATA-FLOW §2): the `EXTERNALLY-MANAGED` marker beside the stdlib, never inside a venv — before any engine command. With the Settings override on, a flow raises it only for pip 23.0, which enforces PEP 668 and has no `--break-system-packages` (it arrived in 23.0.1); pip upkeep refuses a managed Python whatever the setting (DATA-FLOW §7). The `externally-managed-environment` stderr rule is a backstop | PEP 668 protected Python | Use a virtual env; system override only via Settings (discouraged) |
| PD-ENV-003 | probe.py non-zero / unparseable; `ModuleNotFoundError` in engine stderr | broken env metadata | Open logs; recreate the venv. A venv under a folder with non-ASCII characters no longer lands here: since 1.4.0 the probe runs under `-X utf8` (ARCHITECTURE §4) |
| PD-ENG-001 | engine binary not found: a program that cannot be started (uv not on PATH), `No module named pip`, or `ensurepip` failing to rebuild pip. A missing *interpreter* is PD-ENV-001 and an over-long command line PD-SYS-001 — both were this code before 1.4.0 | pip/uv missing | Install engine or switch engine in Settings |
| PD-ENG-002 | pip < 22.2 with plan requested: `no such option: --dry-run` (optparse stops at the first unknown option, and the planner's argv puts `--dry-run` before `--report`), `no such option: --report`, or a dry run that wrote no report | no `--dry-run --report` | One-click "Upgrade pip" then retry |
| PD-ENG-003 | uv output shape unrecognized — a plan from a uv run that **exited 0**. A non-zero exit is classified like any engine failure, which before 1.4.0 it was not: a refused connection came through as this code. pip's report in a shape PipDock cannot read is PD-ENG-999, not this — this code's advice is to switch to pip | uv newer than adapter | Update PipDock; temporarily switch engine to pip |
| PD-ENG-004 | **Raised by PipDock** — a command ran past its watchdog and was stopped (`exec::watchdog`: install and uninstall 30 min, resolve and `list --outdated` 10 min, local queries 3 min, `probe.py` 60 s). In Phase A it fails every row with no Phase B, since a hang retried per package is the same hang N times. Code Health and the audit remap it to PD-HLT-003. A stop is recognised by the error's typed `stop`, not its message, so pip's own `Read timed out` — a network failure, PD-NET-001 — is no longer mistaken for a watchdog | 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` / `conflicting dependencies` / uv's `No solution found when resolving`. A **report**, not an error, under both engines since 1.4.0: pip's `Cannot install A and B …` becomes `report.impossible` as uv's always did, where it used to fail the whole preview | constraints cannot be satisfied | Per-package Skip/Force choices in the preview |
| PD-RES-002 | **Raised by PipDock** after Confirm and before any snapshot: the environment is probed again, and a preview older than 10 minutes or whose installed set no longer matches the one it was resolved over is refused. The same for a removal's guard and a rollback's restore plan, and for a `ruff --fix` whose fixable counts changed. Unreachable until 1.4.0 (DATA-FLOW §9.3) | env changed since preview | Re-run preview |
| PD-RES-003 | a plan is already resolving or executing; also a cache clear while the feature that owns its target runs | 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` / an unloadable backend — pip < 26.3's `BackendUnavailable` traceback, pip ≥ 26.3's `error: backend-unavailable` diagnostic (both frozen in the corpus: `pip-26.2/`, `pip/`), which must precede PD-BLD-003's `Failed to build` because 26.3 ends the diagnostic with that line | 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** — `Requires-Python` is checked by `pipdock-core` (`compat.rs` evaluates; `release.rs` supplies a release's range when the engine does not): an exact pin the user typed before any engine runs, and every change the engine planned after the dry run (ARCHITECTURE §3). A request that is nothing but such pins is this error; otherwise the release is left out and listed in `report.incompatible`, a preview row. Never raised before 1.4.0, though this row described it. (Engine stderr is still not the signal: pip ≥ 26 names the versions it ignored for their Python, but ends with `No matching distribution found`, which classifies as PD-PKG-002; uv ignores an upper bound and plans the release.) | package needs different Python | Shows required range vs env version |
| PD-PKG-002 | `No matching distribution found` (plain); uv's `was not found in the package registry` | name/version typo or yanked | Check spelling/version; `pipdock info <pkg>` |
| PD-PKG-003 | **A preview warning, not a failure, and not classified from stderr**: both engines exit 0 and install a yanked release, so the plan parsers detect it — pip's report marks it `is_yanked`, uv prints `warning: … is yanked` — and carry it in `report.yanked`, shown beside the change it belongs to. Both parsers dropped it before 1.4.0, so it never showed | the plan would install a yanked release | Pick a non-yanked version |
| PD-PKG-004 | hash mismatch / `THESE PACKAGES DO NOT MATCH THE HASHES` | corrupted download | Retry; if it repeats, clear the engine's own cache (`pip cache purge`, `uv cache clean`). PipDock has no command for that — this row named an `engine cache purge` that never existed, and the cache manager (PRD P1-4) covers PipDock's own data, not the engine's |
| PD-NET-001 | timeout / `Connection aborted` / DNS failure / uv's `tcp connect error`; `[WinError 53]` (network path not found) and `[WinError 10013]` (a firewall refusing the socket, raised *as* a `PermissionError`) — both ahead of the permission rules, which took them for PD-PRM-001 until 1.4.0 | offline or PyPI unreachable | Offline banner; retry; search stays local |
| PD-NET-002 | TLS/SSL verification failure. For PipDock's own requests — the index, metadata — read from the error's whole `source()` chain, since reqwest's top-level message never mentions the certificate: every such failure was PD-NET-001 until 1.4.0 | proxy/AV interception | Corporate proxy note; never suggests disabling verification |
| PD-NET-010 | index refresh got an answer that is not a usable index: a non-success status, a document that is not PEP 691 JSON, or an empty project list — refused since 1.4.0 rather than ingested over the index. A connection or TLS failure during the fetch is PD-NET-001/002 | PEP 691 fetch error | Retry later; stale index still searchable (staleness shown) |
| PD-NET-011 | tools venv bootstrap fetch failed — Code Health's, or the Security tab's audit venv | offline during Health setup | Health disabled until online |
| PD-PRM-001 | `PermissionError` writing site-packages; `[WinError 5]`, matched with its bracket, so `[WinError 53]` and `[WinError 59]` are not this | admin-owned Python (Program Files) | v1 blocks: use a venv (elevation is P2-3) |
| PD-PRM-002 | file lock (`[WinError 32]`, bracket included); since 1.4.0 also a file the user chose in the GUI that another program holds open (Windows' sharing violation) | package in use by a running process | Close Python processes using the env — or the program holding the file; retry |
| PD-PRM-003 | a target source file is not writable; since 1.4.0 also a file the user chose in the GUI — an export, a saved report, a requirements file to import — that cannot be read or written for lack of permission (U25: every one of those was PD-SYS-002, "not enough free disk space") | read-only attribute or ACL on a file `ruff --fix` would rewrite, or on the chosen file or folder | For the fix: clear the read-only flag (or fix the permissions) and run it 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. For a chosen file: pick another location, or fix its permissions |
| 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. What raises it is a snapshot that does not exist (or whose freeze file is gone); the rollback preview also lists under it every freeze line no index can supply — editable installs, direct URLs. A release yanked or deleted since the snapshot is **not** detected in the preview (DATA-FLOW §8) and fails as that package's row at execution | deleted/yanked upstream | Partial rollback offered; affected pins listed |
| PD-SYS-001 | `path too long` / `filename or extension is too long`; also Windows error 206 from a spawn or a file PipDock writes — a command line past 32 767 characters, which a large plan reached as argv until 1.4.0 moved requirements into files | MAX_PATH without long-path opt-in | Enable Windows long paths (help link) |
| PD-SYS-002 | disk full (`No space left` / `[WinError 112]`; `ERROR_DISK_FULL` on a file PipDock writes). Until 1.4.0 the GUI answered every file failure with this code | storage | Free space |
| PD-HLT-001..004 | tool missing / non-zero / watchdog timeout / venv creation failed — for the audit venv and pip-audit as for Code Health. One tool whose output cannot be read is that tool's problem, and the other tools still report (1.4.0) | 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. A PD-HLT-003 from `ruff --fix` says files may already have been rewritten |
| PD-INT-001 | panic/unexpected | PipDock bug | Report-bug deep link prefilled. A panic is written to the log by both heads' panic hook, and the CLI prints the log's path (exit 10) |
| PD-ENG-999 | unclassified engine failure; also pip's dry-run report when it is not JSON, or not version 1 (it was PD-ENG-003, whose advice is to switch to pip) | unknown | stderr tail shown; report-bug encouraged (feeds catalog growth) |
`Code::ALL` holds **35** codes; this table has **32** rows because PD-HLT-001..004 share one. `every_variant_is_listed_in_all` and `every_documented_code_has_exactly_one_variant` in `errors/catalog.rs` pin both numbers.
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 — or the code is listed, with the module that raises it, in the `internally_raised` table of `tests/classifier_corpus.rs`, which PD-ENG-004 joined in 1.4.0. **Every WinError needle includes its closing bracket**: Python prints `[WinError N]`, and the bare `winerror 5` also matched 50, 53 and 59, so `[WinError 53] The network path was not found` came out as PD-PRM-001, "use a venv". The corpus runs over `pip/`, `uv/` (uv 0.13's `error:`/`cause:` rendering) and the frozen `uv-0.11/` (miette's `×`/`╰─▶`), and `both_uv_renderings_classify_identically` pins that the two renderings classify alike. Classifying correctly was not enough: `classifier_corpus.rs` passed while uv's adapter never asked the classifier at all (DATA-FLOW §7), so `plan_parsers.rs`'s `every_failed_capture_reaches_the_user_as_the_code_it_was_captured_for` asks the function each resolve actually returns through.
## 3. Presentation rules
GUI: `code · localized one-liner · [Details ⌄ stderr tail ≤ 40 lines] · [Copy full log] · [Report bug]`. CLI: `error[PD-XXX-NNN]: <message>` on stderr, the stderr tail beneath it when there is one, and for an internal error (exit 10) `log: <path>` — the day's `pipdock-cli.<date>.log`. Under `--json` the error envelope is the command's one document on stdout: `{code, message, stderrTail}`, with `stderrTail` null when there is none. **There is no `reason` field**, though this line named one until 1.4.0: `message` is the core's developer-facing detail, in English, because the CLI is English-only (I18N §1), and the GUI receives the same three fields (`WireError`) and looks its one-liner up from `code`. Localization: only the one-liner and action text are localized; codes, messages and stderr never are.
## 4. Bug-report pipeline (owner requirement: console error attached to template)
1. The GUI keeps a ring buffer (last 64 KB, `LOG_RING_BUFFER_BYTES`) of engine stdout/stderr, cleared when a plan begins. It holds engine output only: PipDock's own log (`data\logs\`, new in 1.4.0) is not in it and not in the URL — Settings' Logs row copies that log's tail on its own (`logs_tail`).
2. **Report bug** builds a prefilled GitHub new-issue URL against `.github/ISSUE_TEMPLATE/bug_report.yml`:
`https://github.com/poli0981org/pipdock/issues/new?template=bug_report.yml&pd-version=…&os=…&engine=…&python=…&error-code=…&log-excerpt=…`
Given the environment, `python` carries the engine's version too (`Python 3.12.4 · pip 26.2.1`); the GUI asks for it only when the user clicks, which costs a subprocess (U31).
3. URL budget: GitHub rejects very long URLs, so `log-excerpt` is cut, tail-biased, until its **percent-encoded** form fits 6 000 characters (`BUG_REPORT_EXCERPT_CHARS`). The cap was applied before encoding until 1.4.0, and encoding decides what GitHub sees — an accented letter costs up to nine bytes, a path separator three — so a log full of Vietnamese paths built a ~20 KB link and GitHub answered with an error page instead of the form (M51). The full log is not lost: the error row's *Copy full log* puts the whole ring on the clipboard (`BugReportLink.log`), and hides itself when there is nothing to copy.
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 progress forwarder — which every streaming command shares, so health- and audit-progress lines land there as well as plan-progress — 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, so its excerpt is empty and the URL simply omits the parameter. 1.4.0 gave it a log file (`pipdock-cli.<date>.log`), but `self report-bug` does not read it yet.