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.

feature/Unknown-model-name-redacted · L-260924-b818f9 (#1249)

Thomas Hebrarda4fa20285179
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e733a1d22..80db8292c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
### Fixed
- **The quick start says the Pipelex plugin needs Node.js**: the README's quick start and the documentation's **Quick Start** and **Pipelex Plugin** pages said, in the Claude Code install step, that the plugin needed nothing else to install. Both agents' install steps now say that the plugin's hook and the Pipelex tools run on Node.js, so you need Node.js on your `PATH`; without it the hook passes silently and the tools never start.
+- **An unknown model name keeps its message on a hosted surface**: `ModelChoiceNotFoundError` is now caller-facing, so under STRICT disclosure its message — the model reference the method named and the "Did you mean" suggestions — reaches the caller instead of "An internal error occurred.". A hosted dry run or run of a method naming a model the deck does not know now says which one and what to use instead.
## [v0.64.1] - 2026-09-24
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index f58516fa3..b600fe3e5 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -571,6 +571,7 @@ InferenceErrorCategory.TRANSIENT.is_retryable # True — only TRANSIENT
| Quota / billing exhausted | `CAPACITY` → non-retryable; `UserAction(CHECK_BILLING)`; `error_domain = RUNTIME` → HTTP 500 |
| Bad API key | `CONFIGURATION` → non-retryable; `error_domain = CONFIG` → HTTP 500 |
| Model or deployment not found (provider HTTP 404) | Raises a dedicated `*ModelNotFoundError` sibling (`LLMModelNotFoundError`, `ImgGenModelNotFoundError`, `ExtractModelNotFoundError`, `SearchModelNotFoundError`); operator re-raises `PipeOperatorModelAvailabilityError` |
+| Model reference unknown to the deck (a method naming `gpt-5.1`, a mistyped `@alias` or `$preset`) | `ModelChoiceNotFoundError` → `CONFIGURATION` category, but `error_domain = INPUT` → **HTTP 422**, and caller-facing under STRICT: the message names the reference and its "Did you mean" suggestions, which are all a caller needs to fix the method |
| Content-policy violation | `CONTENT` → non-retryable; `UserAction(CHANGE_INPUT)`; `error_domain = INPUT` → **HTTP 422** |
| Malformed prompt image / bad prompt parameter | `CONTENT` class-level (`PromptImageFormatError`, `LLMPromptParameterError`, …) → `error_domain = INPUT` → **HTTP 422** |
| Any other provider **HTTP 400** | `CONTENT` → `error_domain = INPUT` → **HTTP 422**. This is the widest reach of the derivation: a 400 covers a context-length overflow and a parameter the model rejects alike, and an engine-side request-construction fault lands here too — reported as the caller's to fix, and absent from the 5xx rate |
diff --git a/pipelex/cogt/exceptions.py b/pipelex/cogt/exceptions.py
index 6ad08b2da..9505560d0 100644
--- a/pipelex/cogt/exceptions.py
+++ b/pipelex/cogt/exceptions.py
@@ -210,6 +210,11 @@ class ModelChoiceNotFoundError(CogtError):
# local ``.mthds`` file. An operator-side deck fault surfaces as
# ``ModelDeckPresetValidatonError`` instead, which keeps the derived ``CONFIG``.
error_domain = ErrorDomain.INPUT
+ # The message is caller-facing copy for the same reason: it names only the caller's own model
+ # reference and the deck's public handles (suggestions, sigil hints, available options). Without
+ # the flag, STRICT disclosure on the hosted API replaced it with the generic placeholder, so a
+ # method naming an unknown model failed its dry run with no hint of which model or what to use.
+ _authors_caller_facing_message = True
def __init__(
self,
diff --git a/tests/unit/pipelex/cogt/test_model_choice_not_found_disclosure.py b/tests/unit/pipelex/cogt/test_model_choice_not_found_disclosure.py
new file mode 100644
index 000000000..6ecd8cd3c
--- /dev/null
+++ b/tests/unit/pipelex/cogt/test_model_choice_not_found_disclosure.py
@@ -0,0 +1,35 @@
+from pipelex.base_exceptions import INTERNAL_ERROR_PLACEHOLDER, DisclosureMode, ErrorReport
+from pipelex.cogt.exceptions import ModelChoiceNotFoundError
+from pipelex.cogt.model_backends.model_type import ModelType
+
+
+class TestModelChoiceNotFoundDisclosure:
+ @staticmethod
+ def _make_error() -> ModelChoiceNotFoundError:
+ return ModelChoiceNotFoundError(
+ message="Model handle 'gpt-5.1' was not found in the model deck",
+ model_type=ModelType.LLM,
+ model_choice="gpt-5.1",
+ suggestions=["gpt-5.5", "gpt-5.4"],
+ )
+
+ def test_message_survives_strict_disclosure(self) -> None:
+ """The unknown model name and its suggestions reach a STRICT (hosted) caller instead of the placeholder."""
+ payload = self._make_error().to_error_report().to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert payload["message"] == "Model handle 'gpt-5.1' was not found in the model deck\n\nDid you mean: gpt-5.5, gpt-5.4"
+ assert payload["message"] != INTERNAL_ERROR_PLACEHOLDER
+ assert payload["error_type"] == "ModelChoiceNotFoundError"
+ assert payload["error_domain"] == "input"
+
+ def test_message_survives_the_worker_to_runner_hop(self) -> None:
+ """The hosted path packs the report VERBOSE on the worker, rebuilds it on the runner, then projects STRICT.
+
+ The caller-facing flag is computed where the error is raised (the worker), so it must ride the
+ VERBOSE round trip for the runner's STRICT projection to keep the message.
+ """
+ packed = self._make_error().to_error_report().to_dict()
+ recovered = ErrorReport.from_dict(packed)
+ assert recovered.caller_facing_message is True
+ payload = recovered.to_dict(disclosure_mode=DisclosureMode.STRICT)
+ assert "gpt-5.1" in payload["message"]
+ assert "Did you mean: gpt-5.5, gpt-5.4" in payload["message"]