Files
pipdock/docs/ERROR-CATALOG.md
T
poli0981andClaude Opus 5.5 cfa5b4e1be docs: Add interpreter… in the specs, ACCESSIBILITY.md and the privacy policy
PRD P0-1, UI-SPEC §4, CLI-SPEC (env add/remove, their JSON, --env's new
refusal), CLI-GUIDE, ERROR-CATALOG (PD-ENV-001's new cases, and the
first button its advice ever had) and TESTING's golden count. SECURITY
§2 claimed for two milestones that interpreter paths were canonicalized
before use while the only check was existence; it now describes the
validator that makes it true. PRD also records P0-9's first-run uv
detection, P1-7 and P2 as not planned in maintenance mode.

legal/PRIVACY-POLICY.md 1.3 names the interpreter paths a person adds,
kept until removed, in both languages. With the repository URL it
already changed, the first-run gate shows once in 1.6.0.

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

17 KiB
Raw Blame History

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 inside PipDock's own tools or audit venv 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.