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(validate): unwrap blueprint-stage PipeValidationError so error_type survives (#996)
Louis Choquel389d3350fcc4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0175aa4b5..1d1f7817e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,15 @@# Changelog+## [Unreleased]++### Removed++- **Dead `PipeValidationErrorType` value `img_gen_input_not_text_compatible` (pre-1.0 breaking):** Removed the enum value, which had **zero raise sites** — `PipeImgGen.validate_inputs_with_library` was a no-op. The value encoded an "img-gen inputs must be text-compatible" rule that the current design contradicts: `PipeImgGen` accepts image inputs as a first-class feature (`image_references` / `input_images` for reference images and image editing). The output-side guardrails that *do* hold remain (`llm_output_cannot_be_image`, `inadequate_output_concept`). The value was never emitted, so no real validation output changes.++### Fixed++- **Blueprint-stage `PipeValidationError` lost its `error_type`:** A `PipeValidationError` raised inside a pydantic blueprint validator (the PipeBatch `input_item_name` == `input_list_name` collision, and the SubPipe `batch_over` == `batch_as` collision — both `batch_item_name_collision`) is wrapped by pydantic as a `value_error`, which the blueprint validation-error categorizer did not unwrap, so the item degraded to an uncategorized `blueprint_validation` residual with no `error_type`. The categorizer now unwraps the wrapped `PipeValidationError` from `ctx["error"]` (mirroring the pipe categorizer via the shared `extract_wrapped_pipe_validation_error`), so **any** blueprint-stage `PipeValidationError` keeps its structured `error_type` and recovers its `pipe_code` / `domain_code` / `source` locators from the parse context. The item stays in the `blueprint_validation` category because the fault genuinely surfaces at the parse boundary, before any pipe is instantiated.+## [v0.35.0] - 2026-06-18### Addeddiff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex 35fb559b8..d113b1811 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -68,7 +68,7 @@ Classification happens once, at **Layer 1**. Layers 2–5 are wrappers: they attA bundle-validation failure (`ValidateBundleError`) aggregates per-error data across stages and projects it onto `validation_errors` as a list of typed `ValidationErrorItem`s, so the structured error report an HTTP API surfaces carries machine-mappable diagnostics (not just a single `detail` string). Each item's `category` is one of the **closed** `ValidationErrorCategory` set:-- `blueprint_validation` — interpreter / blueprint-validation faults. This also serves as the **last-resort residual**: a parse-level failure (a TOML-syntax error, an empty blueprint, a bundle-elaborator failure) is raised with only a message and no categorized data, so when *nothing else* produced an item the builder projects that message as one `blueprint_validation` item (no `error_type`, no `source` — the bundle could not become a blueprint at all).+- `blueprint_validation` — interpreter / blueprint-validation faults. A blueprint-stage `PipeValidationError` raised *inside* a pydantic model validator (e.g. the PipeBatch `input_item_name` == `input_list_name` collision, or the SubPipe `batch_over` == `batch_as` collision — both `batch_item_name_collision`) is wrapped by pydantic as a `value_error`; the blueprint categorizer unwraps it (`ctx["error"]`) so the item keeps its structured `error_type` and `pipe_code` / `domain_code` locators instead of degrading to the no-`error_type` residual. The item stays in `blueprint_validation` (not `pipe_validation`) because the fault genuinely surfaced at the parse boundary, before any pipe was instantiated — only the `error_type` is recovered, not the stage. This category also serves as the **last-resort residual**: a parse-level failure (a TOML-syntax error, an empty blueprint, a bundle-elaborator failure) is raised with only a message and no categorized data, so when *nothing else* produced an item the builder projects that message as one `blueprint_validation` item (no `error_type`, no `source` — the bundle could not become a blueprint at all).- `pipe_factory` — pipe-factory failures (e.g. a missing concept).- `pipe_validation` — pipe/concept validation (missing input variable, type mismatch).- `dry_run` — the **residual** dry-run failure (`DryRunError` / `PipeRunError`) with no structured locator. It is projected as one message-only item **only when no categorized error has data**. It is graph-level, so it typically carries **no `source`**.diff --git a/pipelex/core/interpreter/validation_error_categorizer.py b/pipelex/core/interpreter/validation_error_categorizer.pyindex 01caf68ce..dd5cebdb1 100644--- a/pipelex/core/interpreter/validation_error_categorizer.py+++ b/pipelex/core/interpreter/validation_error_categorizer.py@@ -9,6 +9,7 @@ from pipelex.core.bundles.exceptions import ()from pipelex.core.interpreter.helpers import ValidationErrorScope, get_error_scopefrom pipelex.core.pipes.exceptions import PipeValidationErrorType+from pipelex.core.pipes.handle_pipe_errors import extract_wrapped_pipe_validation_errorPIPELEX_BUNDLE_BLUEPRINT_DOMAIN_FIELD = "domain"PIPELEX_BUNDLE_BLUEPRINT_SOURCE_FIELD = "source"@@ -196,6 +197,33 @@ def categorize_blueprint_validation_error(if len(loc) >= 2 and loc[0] == "pipe":pipe_code = str(loc[1])+ # A blueprint-stage ``PipeValidationError`` (e.g. the PipeBatch ``input_item_name`` ==+ # ``input_list_name`` collision raised by ``PipeBatchBlueprint.validate_inputs``, or the SubPipe+ # ``batch_over`` == ``batch_as`` collision raised by ``SubPipeBlueprint.validate_batch_params``) is+ # raised *inside* a pydantic model validator, so pydantic wraps it as a ``value_error`` with the+ # original exception in ``ctx["error"]``. Unwrap it — mirroring the pipe categorizer's+ # ``extract_wrapped_pipe_validation_error`` (one shared helper) — so its structured ``error_type``+ # and locators survive instead of degrading to an uncategorized residual (``error_type`` absent).+ # This recovers the ``error_type`` for ANY blueprint-stage ``PipeValidationError``, not just batch.+ #+ # Category decision: the recovered item stays ``blueprint_validation`` (the only shape this+ # categorizer emits), NOT re-bucketed to ``pipe_validation``. The fault genuinely surfaced at the+ # blueprint-parse boundary — inside ``PipelexBundleBlueprint.model_validate``, before any pipe was+ # instantiated — so ``blueprint_validation`` is the honest stage; we recover the ``error_type``,+ # not the stage. The wrapped error carries no ``pipe_code`` / ``domain_code`` of its own at this+ # boundary, so backfill the locators from the pydantic ``loc`` (the ``pipe.<code>`` prefix) and the+ # bundle dict, preferring any the error does carry.+ wrapped_pipe_error = extract_wrapped_pipe_validation_error(error)+ if wrapped_pipe_error is not None:+ return PipelexBundleBlueprintValidationErrorData(+ error_type=wrapped_pipe_error.error_type,+ domain_code=wrapped_pipe_error.domain_code or domain,+ source=wrapped_pipe_error.file_path or source,+ pipe_code=wrapped_pipe_error.pipe_code or pipe_code,+ message=wrapped_pipe_error.explanation or str(wrapped_pipe_error),+ variable_names=wrapped_pipe_error.variable_names,+ )+error_scope = get_error_scope(loc)# Categorize based on error scopediff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.pyindex ba03e0faa..0d3a2a13e 100644--- a/pipelex/core/pipes/exceptions.py+++ b/pipelex/core/pipes/exceptions.py@@ -109,7 +109,6 @@ class PipeValidationErrorType(StrEnum):CIRCULAR_DEPENDENCY_ERROR = "circular_dependency_error"LLM_OUTPUT_CANNOT_BE_IMAGE = "llm_output_cannot_be_image"- IMG_GEN_INPUT_NOT_TEXT_COMPATIBLE = "img_gen_input_not_text_compatible"INVALID_PIPE_CODE_SYNTAX = "invalid_pipe_code_syntax"UNKNOWN_PIPE_TYPE = "unknown_pipe_type"BATCH_ITEM_NAME_COLLISION = "batch_item_name_collision"diff --git a/pipelex/core/pipes/handle_pipe_errors.py b/pipelex/core/pipes/handle_pipe_errors.pyindex 2e88935b8..4a811cb9b 100644--- a/pipelex/core/pipes/handle_pipe_errors.py+++ b/pipelex/core/pipes/handle_pipe_errors.py@@ -15,12 +15,19 @@ class ModelScope(StrEnum):CONCEPT = "concept"-def _extract_wrapped_pipe_validation_error(error: ErrorDetails) -> PipeValidationError | None:+def extract_wrapped_pipe_validation_error(error: ErrorDetails) -> PipeValidationError | None:"""Extract a wrapped PipeValidationError from a pydantic error if present.When a PipeValidationError is raised inside a model validator, pydantic wraps it.This function attempts to extract the original PipeValidationError from the error context.+ Shared by both validation-error categorizers — the pipe categorizer below+ (Pipe/Concept model validation) and the blueprint categorizer+ (``core.interpreter.validation_error_categorizer``, which unwraps a+ blueprint-stage ``PipeValidationError`` raised by a pydantic validator on the+ blueprint models, e.g. the PipeBatch / SubPipe batch-name collisions). One+ definition so the two categorizers cannot drift on how pydantic wraps the error.+Args:error: Pydantic error details that may contain a wrapped PipeValidationError@@ -87,7 +94,7 @@ def categorize_pipe_validation_error(categorized_errors: list[PipesAndConceptValidationErrorData] = []for error in errors:# First, check if this is a wrapped PipeValidationError- wrapped_pipe_error = _extract_wrapped_pipe_validation_error(error)+ wrapped_pipe_error = extract_wrapped_pipe_validation_error(error)if wrapped_pipe_error:categorized_error = categorize_pipe_validation_with_libraries_error(pipe_error=wrapped_pipe_error)elif model_scope == ModelScope.PIPE:diff --git a/tests/unit/pipelex/core/interpreter/test_validation_error_categorizer.py b/tests/unit/pipelex/core/interpreter/test_validation_error_categorizer.pynew file mode 100644index 000000000..983dead63--- /dev/null+++ b/tests/unit/pipelex/core/interpreter/test_validation_error_categorizer.py@@ -0,0 +1,91 @@+import pytest++from pipelex.core.interpreter.exceptions import PipelexInterpreterError+from pipelex.core.interpreter.interpreter import PipelexInterpreter+from pipelex.core.pipes.exceptions import PipeValidationErrorType++# A PipeBatch whose ``input_item_name`` equals its ``input_list_name`` — the collision+# ``PipeBatchBlueprint.validate_inputs`` raises as a ``PipeValidationError`` from inside a pydantic+# validator (pydantic wraps it as a ``value_error`` with the original in ``ctx["error"]``).+_PIPE_BATCH_COLLISION_MTHDS = """+domain = "batch_collision"+description = "PipeBatch input-name collision"++[concept]+Item = "an item"+Result = "a result"++[pipe.run_batch]+type = "PipeBatch"+description = "Batch over items"+inputs = { items = "Item[]" }+output = "Result[]"+branch_pipe_code = "process_item"+input_list_name = "items"+input_item_name = "items"+"""++# A PipeSequence step whose ``batch_over`` equals its ``batch_as`` — the collision+# ``SubPipeBlueprint.validate_batch_params`` raises (same wrapped-PipeValidationError shape, but+# nested deeper in the ``loc``: ``pipe.<code>.PipeSequence.steps.0``).+_SUB_PIPE_COLLISION_MTHDS = """+domain = "subpipe_collision"+description = "SubPipe batch_over/batch_as collision"++[concept]+Item = "an item"+Result = "a result"++[pipe.run_seq]+type = "PipeSequence"+description = "Sequence that batches a step over its own name"+inputs = { items = "Item[]" }+output = "Result"+steps = [+ { pipe = "process_one", batch_over = "items", batch_as = "items", result = "results" },+]+"""+++class TestBlueprintValidationErrorCategorizer:+ @pytest.mark.parametrize(+ ("test_name", "mthds_content", "expected_pipe_code", "expected_domain_code"),+ [+ ("pipe_batch", _PIPE_BATCH_COLLISION_MTHDS, "run_batch", "batch_collision"),+ ("sub_pipe_sequence_step", _SUB_PIPE_COLLISION_MTHDS, "run_seq", "subpipe_collision"),+ ],+ )+ def test_wrapped_batch_collision_keeps_its_error_type(+ self,+ test_name: str,+ mthds_content: str,+ expected_pipe_code: str,+ expected_domain_code: str,+ ) -> None:+ """A blueprint-stage ``PipeValidationError`` is categorized with its ``error_type``, not dropped.++ Before the fix the blueprint categorizer did not unwrap the pydantic ``value_error`` wrapping a+ ``PipeValidationError``, so the batch-name collision degraded to an uncategorized residual+ (``error_type`` absent). Both raise sites (``PipeBatchBlueprint`` and the nested+ ``SubPipeBlueprint`` step) must now survive as a categorized ``batch_item_name_collision`` item+ carrying the ``pipe_code`` / ``domain_code`` / ``source`` locators recovered from the parse.+ """+ source = f"{test_name}.mthds"+ with pytest.raises(PipelexInterpreterError) as exc_info:+ PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=mthds_content, mthds_source=source)++ collision_items = [+ error for error in exc_info.value.validation_errors if error.error_type == PipeValidationErrorType.BATCH_ITEM_NAME_COLLISION+ ]+ assert len(collision_items) == 1, (+ f"Expected exactly one categorized batch_item_name_collision item, got error_types: "+ f"{[error.error_type for error in exc_info.value.validation_errors]}"+ )+ item = collision_items[0]+ assert item.pipe_code == expected_pipe_code+ assert item.domain_code == expected_domain_code+ assert item.source == source+ assert item.message, "The categorized item must carry the explanatory message"+ # The recovered message is the PipeValidationError's own clean text, not pydantic's+ # "Value error, " prefixed wrapper.+ assert not item.message.startswith("Value error"), f"Expected the unwrapped clean message, got: {item.message!r}"