Task not found in wave plan
1 min read
The completion listener resolves the task a callback refers to and throws when the plan does not contain it.
What the ordering tells you
The lookup happens before the idempotency guard:
if (!task) throw new Error(`Task ${taskCode} not found in wave plan ${wavePlanId}`);
// Idempotency guard: a duplicate completion callback is a no-op.
if (task.status === 'completed') return;
So a duplicate callback for a real task is deliberately harmless — it returns quietly. A callback for a task that does not exist is not treated the same way, and that asymmetry is the design: repeated delivery is expected and benign; referring to something that was never in the plan is a routing error.
What causes it
A stale callback. The plan was replanned or replaced and an agent dispatched under the previous version reported back against the old task code.
Cross-plan misrouting. A callback carrying the right task code and the wrong plan id.
A locally renamed task. Codes are reassigned during flattening and refinement; something holding a pre-refinement code will not match.
How to fix it
Both identifiers are in the message. Check whether that task code exists in that plan — usually it exists in a different one, which points at the routing.
If the plan was replanned mid-flight, the in-flight agents are the problem rather than the callback, and the fix is upstream: work dispatched against a superseded plan should be cancelled rather than allowed to report.
Why not fail quietly
Treating an unknown task code as a no-op would make this error vanish and would lose the only signal that dispatch and reporting have diverged. A callback arriving for work nobody is tracking means something is running that the plan does not know about.