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(validate): unwrap blueprint-stage PipeValidationError so error_type survives (#996)

Louis Choquel389d3350fcc4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Added
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 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 att
A 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.py
index 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_scope
from pipelex.core.pipes.exceptions import PipeValidationErrorType
+from pipelex.core.pipes.handle_pipe_errors import extract_wrapped_pipe_validation_error
PIPELEX_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 scope
diff --git a/pipelex/core/pipes/exceptions.py b/pipelex/core/pipes/exceptions.py
index 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.py
index 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.py
new file mode 100644
index 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}"