Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix: give the entry-pipe lookup failures the INPUT domain (#1180)

Louis Choquel7faacf81f98e
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 92948cd0b..4d3a0490a 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:98cd6d18e164724aa99408c14e3975728c57006cedf1460f1d354e9bf8b5ed9d"
+digest = "sha256:26081eec477bf9277bbb4dec7490c21f5ef92506b61e2e21555979440d760e9d"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-31T16:15:54Z"
-rationale = "Inference errors now derive error_domain from their InferenceErrorCategory, so agent_error's report-first read supersedes the AGENT_ERROR_DOMAINS lookup for every categorized CogtError. Removed the three now-unreachable entries and gave ModelChoiceNotFoundError an explicit class-level INPUT domain, since a mistyped model reference is the caller's to fix even though its category is CONFIGURATION. Reviewed docs/tools/cli/ — agent-cli.md states the generic error envelope and enumerates no dict entries, so nothing there was stale. Updated the Error classification bullet in pipelex/cli/agent_cli/CLAUDE.md, which named the dict as the only source and no longer described how a class self-describes."
+reviewed_at = "2026-09-01T12:40:49Z"
+rationale = "The two validate not-found arms stopped hardcoding PipeNotFoundError as the reported error_type and now name the class that actually failed, since the entry-shaped lookups raise EntryPipeNotFoundError. Reviewed docs/tools/cli/ — agent-cli.md documents the error envelope generically and enumerates no per-command error types, so nothing there was stale. Added the rule to the Error classification bullet in pipelex/cli/agent_cli/CLAUDE.md: with the report-first read, a hardcoded label detaches the reported class from the domain and hint the cause's report puts on the same envelope."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -49,9 +49,9 @@ rationale = "Inference errors now derive error_domain from their InferenceErrorC
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:6e9e8488573fe17d7769608e299879a092ceaf6c"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:d2d0ed19288c2d1c25be1650dd962189fcdb3b86"
-"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3207973c194b096ed5c6ec2d3a955c417789e019"
+"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:27cc2c0b0a7fb5d3a232c6c3ce44663572e14260"
"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:794914167c13975bc0cdff7b301a8268ff1b79b6"
-"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:7c15cf5a7341b774baad2f14540acbef8daebf76"
+"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:2f7dce6a1d3d9987aa14146bac79d6b0e7e985e1"
"pipelex/cli/bundle_target_resolution.py" = "blob:8dccc50b700b877968ed1b2c1c3652ab1c32e956"
"pipelex/cli/cli_factory.py" = "blob:1f859ab3b995e1a67e5fdc812a168d56c338e970"
"pipelex/cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 50ad9a6e2..6e1714cb4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@
### Fixed
+- **An unknown or ambiguous entry `pipe_code` is reported as the caller's mistake, not a server fault**: the two entry-shaped lookups — the ones a CLI argument and an API request field land in — raised the bare `PipeNotFoundError` / `PipeLibraryError`, which declare no `error_domain`, so `ErrorReport.http_status` fell through to 500. A caller typo in the `pipe_code` of a run request therefore came back as an internal error, logged with a traceback and looking retryable to every SDK, for a mistake only the caller could fix — and the same typo already answered 422 on the build routes, which catch those classes explicitly, so one input produced two verdicts depending on the route. Two dedicated classes now carry `ErrorDomain.INPUT` and a `CHANGE_INPUT` action: `EntryPipeNotFoundError` when the entry lookup resolves nothing, `EntryPipeAmbiguousError` when a bare code is declared in several domains. Both subclass the errors they replace, so every existing catcher still matches, and every presentation derives from the domain at once — 422 on the API, the classification the agent CLI reports, the hosted status. Both are caller-facing copy that survives STRICT disclosure, since the message names only the caller's own `pipe_code` and the qualified `pipe_ref`s of bundles they loaded themselves — which is the only thing that makes an ambiguity actionable. In-body resolution is deliberately untouched: `get_optional_pipe` / `get_required_pipe` keep raising the undomained classes, because a ref written inside a bundle is not a caller's input mistake. The one crossing case is translated rather than left to leak: an ambiguous `alias->bare_code` is detected one frame down, inside the alias-scoped search, and the entry lookup re-raises it as `EntryPipeAmbiguousError` keeping the original as its cause. The agent CLI's `validate` arms stopped hardcoding `PipeNotFoundError` as the reported `error_type` and now name the class that actually failed, which is where the domain and hint on that envelope come from.
- **A `native.JSON` input produced a fill-in template the runtime refused**: the input-form deriver grouped `native.JSON` with the three natives the standard calls structureless — `Dynamic`, `Anything` and `Composite` — so its descriptor node was `unknown`, which every inputs-template projection renders as the empty object. But `JSON` is not structureless: its pinned blueprint carries a required `json_obj`, and `JSONContent` refuses a payload without it, so the template a caller was handed for a `JSON` input could never be filled in and submitted. It now expands through the same pinned-structure arm as `Date`, `Html`, `Page`, `TextAndImages` and `SearchResult`, rendering `{"json_obj": {}}`, which the input shaper takes back. The engine's own `_pinned_structure` already drew the line in exactly this place — it returns a structure for `JSON` and `None` for the other three — so the deriver is now consistent with it, and the empty object stays the honest rendering for the natives that genuinely withhold their shape. The shared projection corpus gained a pipe covering all three of the natives it can reach at a slot position, which is where the defect had been sitting unmeasured. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).
- **A bad pipeline-input url survives STRICT disclosure as caller-facing copy**: `PipelineInputContentError` declared `caller_facing_message = True`, which is the name of the *report field*, not of the class-level flag that sets it (`_authors_caller_facing_message`). The declaration therefore did nothing, and the message a caller who simply omitted a url needs to see — the one listing the accepted schemes — was replaced by the generic internal-error placeholder on any surface serializing in STRICT mode, exactly the redaction the declaration was written to prevent. Repairing the flag also revealed why the class could not carry it as it stood: its other raise site reports an unreadable local path, and that message names the resolved path and the `OSError` subclass that rejected it, which would have made STRICT answer "does this server-side path exist, and may the runner read it?" for any authenticated caller of a deployment leaving `is_upload_local_content_enabled` on. The family is therefore split: `PipelineInputUrlMissingError` carries the blank-url message and is caller-facing, while `PipelineInputContentError` keeps the unreadable-path message and stays redacted. Both are pinned in the class-level-metadata sweep, in both directions.
- **The projection corpus's divergence gate sees every engine/projection difference**: `pipelex-dev generate-projection-corpus` states that every difference between the reference projection and the engine's own renderer lands in a declared class, and that an undeclared one fails the command — but the walk missed differences in one direction and absorbed regressions into existing classes in the other, so a projection defect could pass generation green and be committed into `mthds-js` and `mthds-python` as contract bytes. The dict walk iterated only the projected keys, so a field the projection stopped rendering was never compared at all; it is now recorded under an id deliberately absent from the declared reasons, which makes the record refuse rather than pass. The file-leaf arm returned on the expansion without ever comparing the URL both sides carry, where plain recursion would have handed a regressed placeholder to the url-named-text class that absorbs it; the shared keys are now compared strictly. And `fixed-count-honoured` fired on any list longer than the engine's single element, which cannot tell an honoured `Concept[N]` from a wrong count or from a variable `[]` slot wrongly duplicated; it now consults the slot's declared `item_count`, taken from the descriptor. Separately, a pipe declaring no inputs used to abort the whole capture — an empty input form is valid and the projection renders it as `{}`, but the engine's renderer refuses one — and is now captured from the projection alone, with no engine half and nothing compared. Re-measuring the same corpus produces bytes identical to the committed capture, with the same classes at the same counts. See [Projection Fixture Corpus](contribute/generate-projection-corpus.md).
diff --git a/docs/errors/authoring-and-language.md b/docs/errors/authoring-and-language.md
index 95b6a7c25..3458d8a47 100644
--- a/docs/errors/authoring-and-language.md
+++ b/docs/errors/authoring-and-language.md
@@ -112,6 +112,8 @@ own page. Classes are grouped by subsystem.
- [`CrateNormalizationError`](crate-normalization-error.md) — Crate normalization error
- [`DomainLibraryError`](domain-library-error.md) — Domain library
- [`DomainLoadingError`](domain-loading-error.md) — Domain loading
+- [`EntryPipeAmbiguousError`](entry-pipe-ambiguous-error.md) — Entry pipe ambiguous
+- [`EntryPipeNotFoundError`](entry-pipe-not-found-error.md) — Entry pipe not found
- [`LibraryError`](library-error.md) — Library error
- [`LibraryLoadingError`](library-loading-error.md) — Library loading
- [`PipeLibraryError`](pipe-library-error.md) — Pipe library
diff --git a/docs/errors/entry-pipe-ambiguous-error.md b/docs/errors/entry-pipe-ambiguous-error.md
new file mode 100644
index 000000000..234e0cdec
--- /dev/null
+++ b/docs/errors/entry-pipe-ambiguous-error.md
@@ -0,0 +1,22 @@
+---
+title: "Entry pipe ambiguous"
+description: "Reference for the `EntryPipeAmbiguousError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Entry pipe ambiguous
+
+An entry-shaped bare `pipe_code` matched pipes in several domains.
+
+| Field | Value |
+|---|---|
+| `error_type` | `EntryPipeAmbiguousError` |
+| `title` | Entry pipe ambiguous |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/entry-pipe-ambiguous-error/` |
+| `error_domain` | `input` |
+| Defined in | `pipelex.libraries.pipe.exceptions` |
+| Parent class | [`PipeLibraryError`](pipe-library-error.md) |
+| `user_action` | `change_input` — Name one candidate explicitly: 'domain.pipe_code', or 'alias->domain.pipe_code' for a cross-package code. |
+
+[Back to Error Reference](index.md)
diff --git a/docs/errors/entry-pipe-not-found-error.md b/docs/errors/entry-pipe-not-found-error.md
new file mode 100644
index 000000000..f098e8e22
--- /dev/null
+++ b/docs/errors/entry-pipe-not-found-error.md
@@ -0,0 +1,22 @@
+---
+title: "Entry pipe not found"
+description: "Reference for the `EntryPipeNotFoundError` Pipelex error class."
+---
+
+<!-- pipelex:generated -->
+
+# Entry pipe not found
+
+An entry-shaped `pipe_code` — one a human typed — resolved to no pipe.
+
+| Field | Value |
+|---|---|
+| `error_type` | `EntryPipeNotFoundError` |
+| `title` | Entry pipe not found |
+| `type_uri` | `https://docs.pipelex.com/latest/errors/entry-pipe-not-found-error/` |
+| `error_domain` | `input` |
+| Defined in | `pipelex.libraries.pipe.exceptions` |
+| Parent class | [`PipeNotFoundError`](pipe-not-found-error.md) |
+| `user_action` | `change_input` — Check the pipe code for typos and make sure the bundle declaring it is loaded. |
+
+[Back to Error Reference](index.md)
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 351560a96..698c30f77 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -488,6 +488,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| Local file extractor raises a builtin (docling, pypdfium2) | `ValueError` / `RuntimeError` / `FileNotFoundError` → `CONTENT` → `error_domain = INPUT` → **HTTP 422**; `OSError` → `TRANSIENT` (see `_LOCAL_EXTRACT_BY_TYPE_NAME`) |
| LLM returns schema-mismatched JSON | `instructor` re-asks; if exhausted → `UNKNOWN` → no `error_domain` asserted → HTTP 500 |
| Connection dropped mid-request | `AMBIGUOUS` → non-retryable (outcome unknown); `error_domain = RUNTIME` |
+| Unknown or ambiguous entry `pipe_code` (a CLI argument, a run request's field) | `EntryPipeNotFoundError` / `EntryPipeAmbiguousError` → `UserAction(CHANGE_INPUT)`; `error_domain = INPUT` → **HTTP 422**, and caller-facing under STRICT. The in-body lookups (`get_optional_pipe` / `get_required_pipe`) keep raising the undomained `PipeNotFoundError` / `PipeLibraryError`: a ref written inside a bundle is not the caller's input |
| Wrapper exception (no own category) | Inherits cause's classification via enrichment — including the domain the cause derived |
| Failure on a distributed worker | `ErrorReport` recovered from the transport's serialized details — same classification as local |
| Worker exception with no `ErrorReport` | Synthesized fallback report — `error_domain = RUNTIME` |
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index cae77ac58..a71c8fdd4 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -102,7 +102,7 @@ commands/
## Key Patterns
- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough), `concept`/`pipe` (raw TOML). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`).
-- **Error classification**: Each error carries a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. `agent_error()` reads them **report-first**: a `PipelexError` cause's `to_error_report()` wins, and the `AGENT_ERROR_HINTS` / `AGENT_ERROR_DOMAINS` dicts in `agent_output.py` are the fallback for error types that cannot self-describe (builtins, third-party classes, synthetic `error_type` labels). Two ways a class self-describes, and both bar it from the dicts: a class-level `error_domain` / `user_action`, **or** — for the `CogtError` family — an `error_category`, from which `InferenceErrorCategory.error_domain` derives the domain (so `CONTENT` inference failures report `input`, and a dict entry for such a class would be unreachable). `tests/unit/pipelex/cli/test_agent_output_drift.py` enforces both. When a derived domain is wrong for a class, declare an explicit `error_domain` on the class — `ModelChoiceNotFoundError` does, because a mistyped model reference is the caller's to fix even though the category is `CONFIGURATION`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py` and [Error Model](../../../docs/under-the-hood/error-model.md).
+- **Error classification**: Each error carries a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. `agent_error()` reads them **report-first**: a `PipelexError` cause's `to_error_report()` wins, and the `AGENT_ERROR_HINTS` / `AGENT_ERROR_DOMAINS` dicts in `agent_output.py` are the fallback for error types that cannot self-describe (builtins, third-party classes, synthetic `error_type` labels). Two ways a class self-describes, and both bar it from the dicts: a class-level `error_domain` / `user_action`, **or** — for the `CogtError` family — an `error_category`, from which `InferenceErrorCategory.error_domain` derives the domain (so `CONTENT` inference failures report `input`, and a dict entry for such a class would be unreachable). `tests/unit/pipelex/cli/test_agent_output_drift.py` enforces both. Because the read is report-first, the `error_type` an arm passes must name the class that actually failed — `type(exc).__name__`, not the base class the `except` caught. A hardcoded label detaches the reported class from the domain and hint riding the same envelope from the cause's report, so a consumer reading `error_type` is told one class produced a classification only another declares; the `validate pipe` / `validate bundle` not-found arms did exactly that until the entry-shaped lookups gained their own INPUT-domain classes. A synthetic label is still legitimate where there is no exception class to name, and that is what the dicts key on. When a derived domain is wrong for a class, declare an explicit `error_domain` on the class — `ModelChoiceNotFoundError` does, because a mistyped model reference is the caller's to fix even though the category is `CONFIGURATION`. The `error_domain` also drives the HTTP-status mapping for downstream APIs — see `error_domain_to_http_status()` in `pipelex/base_exceptions.py` and [Error Model](../../../docs/under-the-hood/error-model.md).
- **The `migration` field on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the test for whether the migration history has anything to say. Whether a command *repairs* it is the separate `would_write` field: true means the configuration is *old*, and the loop is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`; false means the block is a diagnosis its `plans` carry and the command would rewrite nothing, so branching on presence alone sends an agent to a run with nothing to do. Its `plans` are the same shape that command emits under its own `plans` key. `error_domain` stays `config`: a domain the hook specification does not know routes to BLOCK, which would stop an agent instead of telling it what to run. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".
- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`.
- **Async core**: Run and validate are async — commands use `asyncio.run()`.
diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
index 3207973c1..27cc2c0b0 100644
--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
@@ -187,7 +187,8 @@ def validate_bundle_cmd(
raise typer.Exit(1)
except PipeNotFoundError as exc:
- agent_error(str(exc), error_type="PipeNotFoundError", cause=exc, exit_code=2)
+ # The real class, not the caught base — see the same arm in `validate pipe`.
+ agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)
except FileNotFoundError as exc:
agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)
diff --git a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
index 7c15cf5a7..2f7dce6a1 100644
--- a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
@@ -188,7 +188,10 @@ def validate_pipe_cmd(
error_message = str(exc)
if pipe_code == "all":
error_message += " Did you mean '--all'?"
- agent_error(error_message, error_type="PipeNotFoundError", cause=exc, exit_code=2)
+ # The label is the real class, not the caught base: the entry-shaped lookup raises
+ # EntryPipeNotFoundError, whose INPUT domain and hint already ride this envelope from the
+ # report. Hardcoding the base name would attribute them to a class that declares neither.
+ agent_error(error_message, error_type=type(exc).__name__, cause=exc, exit_code=2)
except ValidateBundleError as exc:
# Invalid verdict (see the --all arm): structured failure envelope; validation_errors[] is the
diff --git a/pipelex/libraries/pipe/exceptions.py b/pipelex/libraries/pipe/exceptions.py
index 96c4b90f4..41e81efd8 100644
--- a/pipelex/libraries/pipe/exceptions.py
+++ b/pipelex/libraries/pipe/exceptions.py
@@ -1,3 +1,5 @@
+from pipelex.base_exceptions import ErrorDomain
+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.libraries.exceptions import LibraryError
@@ -7,3 +9,53 @@ class PipeLibraryError(LibraryError):
class PipeNotFoundError(PipeLibraryError):
pass
+
+
+class EntryPipeNotFoundError(PipeNotFoundError):
+ """An entry-shaped `pipe_code` — one a human typed — resolved to no pipe.
+
+ The in-body sibling `PipeNotFoundError` reports a ref written inside a bundle, which is a fault
+ of the loaded methods and stays unclassified. This one reports a code the caller supplied at an
+ entry point (a CLI argument, the `pipe_code` field of a run request), so it is the caller's own
+ typo: INPUT domain, which every presentation derives from at once — 422 rather than a 500 that
+ reads as retryable to every SDK.
+
+ Caller-facing copy: the message names only the caller's own `pipe_code`, so STRICT disclosure
+ keeps it verbatim. The flag spans every raise site of the class, and this class has exactly one.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ user_action = UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ detail="Check the pipe code for typos and make sure the bundle declaring it is loaded.",
+ )
+ _declared_title = "Entry pipe not found"
+ _authors_caller_facing_message = True
+
+
+class EntryPipeAmbiguousError(PipeLibraryError):
+ """An entry-shaped bare `pipe_code` matched pipes in several domains.
+
+ Raised only by the entry lookup, which searches a bare code across domains precisely because a
+ human typed it. Refusing to guess is the right answer, but it is the caller who picks the winner
+ — INPUT domain, same reasoning as :class:`EntryPipeNotFoundError`.
+
+ Caller-facing copy: the message names the caller's own `pipe_code` and the qualified `pipe_ref`s
+ of bundles they loaded themselves, so it survives STRICT disclosure intact — and it has to, since
+ the candidates are the only thing that makes the error actionable. That holds because the entry
+ library carries only the caller's own bundles: the runner passes no `library_dirs` and no
+ deployment sets `PIPELEXPATH`, so no host-private `.mthds` is merged into it. It is a property of
+ how the runner is deployed, not a rule this class enforces — a deployment that did merge a host
+ library would put host `pipe_ref`s in this message.
+ """
+
+ error_domain = ErrorDomain.INPUT
+ user_action = UserAction(
+ kind=UserActionKind.CHANGE_INPUT,
+ # Both spellings, because both raise sites reach this one detail: the bare-code arm is fixed by
+ # 'domain.pipe_code', while the cross-package arm translated from the alias-scoped search needs
+ # the alias too — a bare 'domain.pipe_code' does not reach a dependency pipe at all.
+ detail="Name one candidate explicitly: 'domain.pipe_code', or 'alias->domain.pipe_code' for a cross-package code.",
+ )
+ _declared_title = "Entry pipe ambiguous"
+ _authors_caller_facing_message = True
diff --git a/pipelex/libraries/pipe/pipe_library.py b/pipelex/libraries/pipe/pipe_library.py
index a0028f58b..2826fcc6c 100644
--- a/pipelex/libraries/pipe/pipe_library.py
+++ b/pipelex/libraries/pipe/pipe_library.py
@@ -8,7 +8,7 @@ from typing_extensions import override
from pipelex import pretty_print
from pipelex.core.qualified_ref import QualifiedRef
-from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundError
+from pipelex.libraries.pipe.exceptions import EntryPipeAmbiguousError, EntryPipeNotFoundError, PipeLibraryError, PipeNotFoundError
from pipelex.libraries.pipe.pipe_library_abstract import PipeLibraryAbstract
from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
@@ -111,8 +111,22 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
Aliased dependency entries are excluded from the search. Without that, installing an
unrelated package could make a host pipe's bare code ambiguous — reintroducing, through this
door, exactly the contextual instability the strict in-body rule exists to remove.
+
+ Every failure this door reports is the caller's own typo, so it is raised as an entry-shaped
+ error carrying the INPUT domain — including the one detected one frame down, in the
+ alias-scoped bare-remainder search inside `get_optional_pipe`, which is translated here. The
+ in-body door keeps the unclassified errors: the same ambiguity read from inside a bundle is
+ not a caller's input mistake.
"""
- pipe = self.get_optional_pipe(pipe_code=pipe_code)
+ try:
+ pipe = self.get_optional_pipe(pipe_code=pipe_code)
+ except PipeNotFoundError:
+ # A miss is not an ambiguity. `get_optional_pipe` raises none today, but `PipeNotFoundError`
+ # IS a `PipeLibraryError`, so without this arm a future one would be re-raised under a class
+ # asserting the opposite — and handed a `user_action` naming candidates that never existed.
+ raise
+ except PipeLibraryError as exc:
+ raise EntryPipeAmbiguousError(str(exc)) from exc
if pipe is not None:
return pipe
@@ -126,8 +140,8 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
return matches[0]
if len(matches) > 1:
candidates = sorted(match.pipe_ref for match in matches)
- msg = f"Pipe code '{pipe_code}' is ambiguous — it is declared by {candidates}. Name one of them explicitly."
- raise PipeLibraryError(msg)
+ msg = f"Pipe code '{pipe_code}' is ambiguous — it is declared by {candidates}. Name one of them explicitly, as 'domain.pipe_code'."
+ raise EntryPipeAmbiguousError(msg)
return None
@override
@@ -138,7 +152,7 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
f"Pipe '{pipe_code}' could not be resolved. Check for typos and make sure its bundle is loaded. "
"A bare code only matches this library's own domains — a pipe from a dependency package must be named 'alias->pipe_code'."
)
- raise PipeNotFoundError(msg)
+ raise EntryPipeNotFoundError(msg)
return the_pipe
def add_dependency_pipe(self, *, alias: str, pipe: PipeAbstract) -> None:
diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txt
index 7b7532c25..6422223fd 100644
--- a/tests/data/errors/error_identity.txt
+++ b/tests/data/errors/error_identity.txt
@@ -73,6 +73,8 @@ DuplicateOrchestratorError | Duplicate orchestrator | https://docs.pipelex.com/l
DuplicatePipeFuncExecutorError | Duplicate pipe func executor | https://docs.pipelex.com/latest/errors/duplicate-pipe-func-executor-error/
DuplicateSecretsProviderError | Duplicate secrets provider | https://docs.pipelex.com/latest/errors/duplicate-secrets-provider-error/
DuplicateStorageProviderError | Duplicate storage provider | https://docs.pipelex.com/latest/errors/duplicate-storage-provider-error/
+EntryPipeAmbiguousError | Entry pipe ambiguous | https://docs.pipelex.com/latest/errors/entry-pipe-ambiguous-error/
+EntryPipeNotFoundError | Entry pipe not found | https://docs.pipelex.com/latest/errors/entry-pipe-not-found-error/
EnvVarNotFoundError | Environment variable not set | https://docs.pipelex.com/latest/errors/env-var-not-found-error/
EventLogError | Event log | https://docs.pipelex.com/latest/errors/event-log-error/
EventLogReadError | Event log read | https://docs.pipelex.com/latest/errors/event-log-read-error/
diff --git a/tests/unit/pipelex/exceptions/test_class_level_metadata.py b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
index 0d7e8498b..622fa7dae 100644
--- a/tests/unit/pipelex/exceptions/test_class_level_metadata.py
+++ b/tests/unit/pipelex/exceptions/test_class_level_metadata.py
@@ -16,6 +16,7 @@ from pipelex.cogt.exceptions import (
SdkTypeError,
)
from pipelex.core.stuffs.exceptions import DateContentError
+from pipelex.libraries.pipe.exceptions import EntryPipeAmbiguousError, EntryPipeNotFoundError, PipeLibraryError, PipeNotFoundError
from pipelex.mthds_parsing.exceptions import MthdsParserError
from pipelex.pipeline.exceptions import (
PipeExecutionError,
@@ -54,6 +55,10 @@ class TestClassLevelMetadata:
("pipe_execution", PipeExecutionError("boom"), ErrorDomain.RUNTIME),
("validate_bundle", ValidateBundleError("boom"), ErrorDomain.INPUT),
("pipeline_input_content", PipelineInputContentError("boom"), ErrorDomain.INPUT),
+ # The entry-shaped lookups report a pipe_code the caller supplied, so a typo is theirs
+ # to fix — 422, never the 500 an undomained error renders as.
+ ("entry_pipe_not_found", EntryPipeNotFoundError("boom"), ErrorDomain.INPUT),
+ ("entry_pipe_ambiguous", EntryPipeAmbiguousError("boom"), ErrorDomain.INPUT),
("interpreter", MthdsParserError("boom"), ErrorDomain.INPUT),
("setup", PipelexSetupError("boom"), ErrorDomain.CONFIG),
("config", PipelexConfigError("boom"), ErrorDomain.CONFIG),
@@ -74,6 +79,16 @@ class TestClassLevelMetadata:
[
("pipeline_execution", _PIPELINE_EXEC_ERROR, "Check pipe_stack to identify which pipe failed"),
("validate_bundle", ValidateBundleError("boom"), "Check the validation_errors array for specific issues"),
+ (
+ "entry_pipe_not_found",
+ EntryPipeNotFoundError("boom"),
+ "Check the pipe code for typos and make sure the bundle declaring it is loaded.",
+ ),
+ (
+ "entry_pipe_ambiguous",
+ EntryPipeAmbiguousError("boom"),
+ "Name one candidate explicitly: 'domain.pipe_code', or 'alias->domain.pipe_code' for a cross-package code.",
+ ),
],
)
def test_user_action(self, _topic: str, exc: PipelexError, expected_detail: str) -> None:
@@ -117,6 +132,14 @@ class TestClassLevelMetadata:
# caller-facing would let STRICT disclosure answer "does this server-side path exist,
# and may the runner read it?" for any authenticated caller.
("pipeline_input_content", PipelineInputContentError("boom"), False),
+ # The entry-lookup messages name the caller's own pipe_code and the qualified pipe_refs
+ # of bundles they loaded themselves — nothing server-side — and the candidate list is
+ # the only thing that makes an ambiguity actionable, so redacting it would gut the error.
+ ("entry_pipe_not_found", EntryPipeNotFoundError("boom"), True),
+ ("entry_pipe_ambiguous", EntryPipeAmbiguousError("boom"), True),
+ # The in-body doors stay redacted: their refs come from a bundle, not from the caller.
+ ("pipe_not_found", PipeNotFoundError("boom"), False),
+ ("pipe_library", PipeLibraryError("boom"), False),
("csv", CsvError("boom"), True),
("unknown_storage_method", UnknownStorageMethodError(method="bogus", registered_methods=["local", "s3"]), True),
("unknown_secrets_method", UnknownSecretsMethodError(method="bogus", registered_methods=["env"]), True),
diff --git a/tests/unit/pipelex/libraries/test_pipe_library_lookup.py b/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
index 51b179f8b..2a357d782 100644
--- a/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
+++ b/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
@@ -3,7 +3,8 @@ from typing import Any
import pytest
from pytest_mock import MockerFixture
-from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundError
+from pipelex.base_exceptions import ErrorDomain
+from pipelex.libraries.pipe.exceptions import EntryPipeAmbiguousError, EntryPipeNotFoundError, PipeLibraryError, PipeNotFoundError
from pipelex.libraries.pipe.pipe_library import PipeLibrary
@@ -78,24 +79,96 @@ class TestPipeLibraryLookup:
assert library.get_optional_entry_pipe("compute_score") is mock_pipe
def test_entry_pipe_ambiguous_bare_code_raises(self, mocker: MockerFixture):
- """Two domains declaring the code: refuse to guess, and name both so the user can pick."""
+ """Two domains declaring the code: refuse to guess, and name both so the user can pick.
+
+ The code came from a human — a CLI argument or an API request field — so the failure is the
+ caller's to fix: INPUT domain, 422, never a server fault the caller would retry.
+ """
library = PipeLibrary.make_empty()
library.root["scoring.compute_score"] = _make_stub_pipe(mocker, code="compute_score", domain_code="scoring")
library.root["analytics.compute_score"] = _make_stub_pipe(mocker, code="compute_score", domain_code="analytics")
- with pytest.raises(PipeLibraryError, match="is ambiguous") as exc_info:
+ with pytest.raises(EntryPipeAmbiguousError, match="is ambiguous") as exc_info:
library.get_optional_entry_pipe("compute_score")
assert "analytics.compute_score" in str(exc_info.value)
assert "scoring.compute_score" in str(exc_info.value)
+ report = exc_info.value.to_error_report()
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.http_status == 422
+
def test_entry_pipe_no_match_returns_none(self):
library = PipeLibrary.make_empty()
assert library.get_optional_entry_pipe("nonexistent") is None
def test_entry_pipe_required_raises_not_found(self):
+ """An entry code that resolves to nothing is a caller typo, reported as INPUT / 422."""
library = PipeLibrary.make_empty()
- with pytest.raises(PipeNotFoundError):
+ with pytest.raises(EntryPipeNotFoundError) as exc_info:
library.get_required_entry_pipe("nonexistent")
+ report = exc_info.value.to_error_report()
+ assert report.error_domain == ErrorDomain.INPUT
+ assert report.http_status == 422
+
+ def test_entry_pipe_translates_aliased_ambiguity(self, mocker: MockerFixture):
+ """An ambiguous `alias->bare_code` reaching the entry lookup is still the caller's typo.
+
+ The ambiguity is detected one frame down, inside `get_optional_pipe`'s alias-scoped
+ bare-remainder search, which raises the domain-less in-body error. The entry lookup
+ translates it so the whole entry surface classifies uniformly, keeping the original as
+ `__cause__`.
+ """
+ library = PipeLibrary.make_empty()
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"))
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="analytics"))
+
+ with pytest.raises(EntryPipeAmbiguousError) as exc_info:
+ library.get_optional_entry_pipe("lib->compute_score")
+
+ cause = exc_info.value.__cause__
+ assert isinstance(cause, PipeLibraryError)
+ assert not isinstance(cause, EntryPipeAmbiguousError)
+ assert exc_info.value.to_error_report().error_domain == ErrorDomain.INPUT
+
+ def test_entry_pipe_does_not_translate_a_miss_into_an_ambiguity(self, mocker: MockerFixture):
+ """A miss surfacing from `get_optional_pipe` must not be re-raised as an ambiguity.
+
+ `PipeNotFoundError` IS a `PipeLibraryError`, so the translation arm would otherwise catch it
+ and report it under a class asserting the opposite — with a `user_action` naming candidates
+ that never existed. No in-body raise site produces one today, so the raise is injected.
+ """
+ library = PipeLibrary.make_empty()
+ # Patched on the class, not the instance: PipeLibrary is a pydantic RootModel and rejects the
+ # per-instance attribute set. mocker undoes it at teardown.
+ mocker.patch.object(PipeLibrary, "get_optional_pipe", side_effect=PipeNotFoundError("boom"))
+
+ with pytest.raises(PipeNotFoundError) as exc_info:
+ library.get_optional_entry_pipe("compute_score")
+ assert not isinstance(exc_info.value, EntryPipeAmbiguousError)
+
+ def test_in_body_aliased_ambiguity_is_not_translated(self, mocker: MockerFixture):
+ """The same lookup through the in-body door keeps the plain, unclassified error.
+
+ In-body resolution failures are not a caller's input mistake — the ref was written in a
+ bundle — so the entry classification must not leak onto them.
+ """
+ library = PipeLibrary.make_empty()
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"))
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="analytics"))
+
+ with pytest.raises(PipeLibraryError) as exc_info:
+ library.get_optional_pipe("lib->compute_score")
+ assert not isinstance(exc_info.value, EntryPipeAmbiguousError)
+ assert exc_info.value.to_error_report().error_domain is None
+
+ def test_in_body_required_miss_stays_unclassified(self):
+ """`get_required_pipe` is the in-body door and keeps raising the plain, domain-less error."""
+ library = PipeLibrary.make_empty()
+ with pytest.raises(PipeNotFoundError) as exc_info:
+ library.get_required_pipe("scoring.nonexistent")
+ assert not isinstance(exc_info.value, EntryPipeNotFoundError)
+ assert exc_info.value.to_error_report().error_domain is None
+
def test_entry_pipe_ignores_aliased_dependency_entries(self, mocker: MockerFixture):
"""An installed package must not make a host pipe's bare code ambiguous.
diff --git a/wip/entry-pipe-error-domain/plan.md b/wip/entry-pipe-error-domain/plan.md
new file mode 100644
index 000000000..2926f2238
--- /dev/null
+++ b/wip/entry-pipe-error-domain/plan.md
@@ -0,0 +1,83 @@
+---
+status: active
+item: L-260829-fa8267
+---
+
+# Give the entry-pipe lookup failures the INPUT domain
+
+## The bug, verified
+
+An ambiguous or unknown entry `pipe_code` on the run routes is reported as a server fault. Probe on this tree (dev):
+
+```python
+from pipelex.libraries.pipe.exceptions import PipeLibraryError, PipeNotFoundError
+
+PipeLibraryError("…").to_error_report() # error_domain=None, http_status=500
+PipeNotFoundError("…").to_error_report() # error_domain=None, http_status=500
+```
+
+Both classes are declared bare (`pipelex/libraries/pipe/exceptions.py`), so `ErrorReport.http_status` falls through `error_domain_to_http_status(None)` → 500 (`pipelex/base_exceptions.py`). The raise sites are the entry-shaped lookup in `pipelex/libraries/pipe/pipe_library.py`: `get_optional_entry_pipe` raises `PipeLibraryError` on an ambiguous bare code, and `get_required_entry_pipe` raises `PipeNotFoundError` on a miss. The run path reaches them through `pipeline_run_setup.py` (`get_required_entry_pipe` on a caller-supplied `pipe_code`), so a caller typo surfaces as a 500, logged with a traceback, looking retryable to every SDK — for a mistake only the caller can fix. Meanwhile `pipelex-api`'s build routes catch `PipeLibraryError` and answer 422 (`api/routes/pipelex/crate_ops.py`), so the same typo gets two different verdicts depending on the route. `pipelex-api/api/exception_handlers.py`'s `_ERROR_TYPE_STATUS_OVERRIDES` has no entry for either class — and per the ledger item, the runtime-side domain is the better fix anyway: every presentation (CLI exit code, API status, hosted) derives from it at once.
+
+## Design
+
+- **Two dedicated classes** in `pipelex/libraries/pipe/exceptions.py`, subclassing the existing ones so every current catcher keeps working (`bundle_validator.py`, `validate_bundle.py`, `pipe_parallel.py`, the CLI commands, and `pipelex-api`'s `crate_ops.py` / `build/runner.py` all catch the bases):
+ - `EntryPipeNotFoundError(PipeNotFoundError)` — raised by `get_required_entry_pipe` when the lookup resolves nothing.
+ - `EntryPipeAmbiguousError(PipeLibraryError)` — raised by `get_optional_entry_pipe` when a bare code matches several domains.
+- **Both carry** `error_domain = ErrorDomain.INPUT`, a `user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, …)`, a `_declared_title`, and `_authors_caller_facing_message = True` — the messages describe only the caller's own `pipe_code` and the qualified `pipe_ref` candidates of their own loaded bundles, so STRICT disclosure may keep them verbatim. The flag spans every raise site of a class; these classes have exactly the two entry-lookup raise sites, so that is safe. Imports mirror `pipelex/pipeline/exceptions.py` (`ErrorDomain` from `base_exceptions`, `UserAction`/`UserActionKind` from `cogt/inference/error_classification`).
+- **Messages** keep naming the candidates as sorted qualified `pipe_ref`s (the ambiguous message already does) and say what to send instead: name one candidate explicitly as `domain.pipe_code` in the `pipe_code` field / CLI argument.
+- **In-body semantics untouched.** `get_optional_pipe` / `get_required_pipe` keep raising the existing classes. One edge: an entry-shaped `alias->bare_code` that is ambiguous inside the dependency raises `PipeLibraryError` from *inside* `get_optional_pipe` (the alias-scoped bare-remainder search) even when the call came through the entry lookup. `get_optional_entry_pipe` will translate that: wrap its `get_optional_pipe` delegation, catch `PipeLibraryError`, re-raise as `EntryPipeAmbiguousError` `from` the original. In-body callers going directly through `get_optional_pipe` see no change.
+- **No `pipelex-api` change needed.** With the domain on the classes, `ErrorReport.http_status` yields 422 and `_ERROR_TYPE_STATUS_OVERRIDES` stays untouched; the build routes' explicit 422 catch is unaffected (subclasses still match).
+
+## Phases
+
+### Phase 1 — red tests
+
+In `tests/unit/pipelex/libraries/test_pipe_library_lookup.py` (extend the existing suite):
+
+- An ambiguous bare entry code (two domains declaring the same pipe code) raises `EntryPipeAmbiguousError`; the message names both qualified `pipe_ref`s; `to_error_report()` has `error_domain == ErrorDomain.INPUT` and `http_status == 422`.
+- An unknown entry code raises `EntryPipeNotFoundError`; same report assertions.
+- The entry-shaped `alias->bare_code` ambiguity is translated to `EntryPipeAmbiguousError` (with the `PipeLibraryError` as `__cause__`), while the same lookup through `get_optional_pipe` still raises plain `PipeLibraryError`.
+- In-body miss through `get_required_pipe` still raises plain `PipeNotFoundError` with no domain (guards the "untouched" constraint).
+
+Run them, watch them fail for the right reason.
+
+### Phase 2 — implement
+
+- Add the two classes to `pipelex/libraries/pipe/exceptions.py`.
+- `pipe_library.py`: swap the two raise sites; add the translation wrapper in `get_optional_entry_pipe` around its `get_optional_pipe` call.
+- Regenerate the error artifacts — a new error class is invisible to everything but the full suite until this is done: `make gei` (error-identity snapshot) and `make gep` (error reference pages under `docs/errors/`).
+- Tests from Phase 1 go green.
+
+### Phase 3 — sweep, docs, gates
+
+- Sweep callers of the two lookups (`interpreter_hub.py` wrappers, `pipeline_run_setup.py`, CLI `show`/`which`/`validate`/`codegen`) for any message-matching or type branching that the new subclasses would change — none expected, verify anyway.
+- CHANGELOG.md under `## [Unreleased]`: one condensed entry (fixed: entry-pipe lookup failures now carry the INPUT domain → 422 instead of 500 on the run routes).
+- `make agent-check`, then full `make agent-test` (the identity snapshot and error-page tests only run there).
+
+### Checkpoint
+
+All three phases landed. `make agent-check` and the full `make agent-test` are green.
+
+**Deviations from the design, and one thing the sweep actually found.**
+
+The alias-ambiguity translation went in as designed, wrapping only the `get_optional_pipe` delegation in `get_optional_entry_pipe` and re-raising `from` the original. Nothing else about the in-body path moved: the plain `PipeLibraryError` / `PipeNotFoundError` still come out of `get_optional_pipe` and `get_required_pipe` with no domain, pinned in both directions by the lookup suite.
+
+The one real find was outside the design. `pipelex/cli/agent_cli/commands/validate/pipe_cmd.py` and `bundle_cmd.py` caught `PipeNotFoundError` and passed `error_type="PipeNotFoundError"` as a hardcoded string. Because `agent_error` reads the domain and hint report-first from the cause, those envelopes would have carried `EntryPipeNotFoundError`'s INPUT domain and `CHANGE_INPUT` hint while naming a class that declares neither — an envelope contradicting itself for anyone branching on `error_type`. Both arms now pass `type(exc).__name__`. That is a wire-visible change for a consumer keyed on the old string, which is the point: the string was already the wrong answer. No test asserted on it, and neither `AGENT_ERROR_HINTS` nor `AGENT_ERROR_DOMAINS` held an entry for it.
+
+That edit opened the `cli-docs` drift contract. Reviewed, acked, and the rule is now written into `pipelex/cli/agent_cli/CLAUDE.md`'s Error-classification bullet, since the trap generalizes: with a report-first read, any hardcoded `error_type` label detaches the reported class from the classification riding beside it.
+
+**Docs.** `docs/under-the-hood/error-model.md` gained a Behavior Summary row for the entry lookups, stating the in-body contrast. `docs/errors/entry-pipe-not-found-error.md` and `entry-pipe-ambiguous-error.md` are the generated pages (`make gep`), and `tests/data/errors/error_identity.txt` the regenerated snapshot (`make gei`).
+
+**Also pinned.** `tests/unit/pipelex/exceptions/test_class_level_metadata.py` gained both classes in the domain, user-action and caller-facing sweeps, plus their undomained, non-caller-facing parents — so a future refactor that lets the entry classification leak onto the in-body doors, or that quietly drops it from the entry ones, fails there too.
+
+Next: open the PR against `dev` with `Closes L-260829-fa8267` in the body. After the merge, the blocked runner-side item L-260829-a30018 becomes workable.
+
+### Review round
+
+Two corrections on top of the checkpoint, both inside the design's own surface.
+
+`EntryPipeAmbiguousError`'s `user_action` detail said `Name one of the listed candidates explicitly, as 'domain.pipe_code'.` That is right for the bare-code arm and wrong for the arm translated from the alias-scoped search, whose message names domains inside a dependency package: a caller obeying it and sending `scoring.compute_score` reaches the entry lookup's host-only match (`pipe_library.py`'s `has_cross_package_prefix` exclusion), resolves nothing, and gets `EntryPipeNotFoundError` instead. One `user_action` serves both raise sites, so the detail now carries both spellings. `make gep` regenerated the ambiguous page.
+
+The translation arm caught `PipeLibraryError`, and `PipeNotFoundError` is one — so a miss raised from inside `get_optional_pipe` would have been re-raised as a class asserting an ambiguity, carrying a hint about candidates that never existed. No in-body site raises one there today, which is exactly why the trap would have been silent; `get_optional_entry_pipe` now lets `PipeNotFoundError` through untranslated. Pinned by `test_entry_pipe_does_not_translate_a_miss_into_an_ambiguity`, which injects the raise and was mutation-checked red with the arm removed.
+
+The review also found the same defect class one module over, left out to keep this diff at its stated scope: `validate_bundle.py`'s `_pipes_to_dry_run` raises the undomained `PipeNotFoundError` for a caller-supplied `--pipe` / `pipe_ref`, and `pipelex-api`'s build route maps it to 422 by hand. Filed as L-260901-296dfb.