When a task is blocked
A blocked task is one the engine did everything it could on its own with — and now needs you. Two ways a task gets here, and one common look-alike to know about.
Reason 1 — can't find a recipient for the task
Every task is aimed at a stakeholder role (e.g. "lender", "title", "seller"). If your deal doesn't have a contact in that role yet — or if the matching contact has no email on file — the engine can't send. The task lands as a Blocked card with a caption like:
- Needs Title Company contact — no escrow officer or title company on file
- Needs Seller contact — no seller contact (or no email on the one you have)
- Needs Lender contact — no lender on file
These are the most common, and they're the fastest to fix.
Reason 2 — overdue past escalation
If a task sat in waiting_response (we sent something, nobody replied) for longer than its escalate_after_days setting (usually 1–2 days past due), the daily escalation cron flips the status to blocked. These show up with the original task title and a history of what the engine tried — typically "Sent on Apr 10, nudged twice, no reply, 3 days overdue."
What about pending tasks that say "Waiting on: ..."?
These look like blockers but they aren't. A pending overdue task whose caption reads Waiting on: [some other task] is correctly held by the engine because an upstream task hasn't completed yet. Example: "Title confirms closing package ready" is waiting on "Confirm commitment letter received". The engine isn't broken — it's gating activation until the prereq clears.
If you know the prereq is informally done (e.g. you talked to the lender on the phone and they've already sent the package), mark the upstream task complete from its kebab menu. The downstream task will activate on the next coordination tick.
How to clear a blocked task
Each blocked card offers a few actions:
Add the missing contact (most common). Click Add contact on the blocked card. A form opens — role, name, email. Fill it in and save. The contact is created on the deal, saved to your Directory for future deals, and every blocked task that needed that role unblocks automatically on the next render. You don't need to manually unblock each one.
Override the block. If you've handled the underlying ask outside the app (a phone call, an in-person follow-up), click Override block. The card walks you through marking the task complete with a reason — fully audit-logged.
Skip the task. If the task genuinely doesn't apply to this deal (no title company on a cash deal with a buyer's attorney handling closing), click Skip task and add a reason. The task moves to skipped and any prereq-gated downstream tasks unlock too.
Reopen after the fact. Blocked tasks can be reopened back to pending from the kebab menu if the situation changes (e.g. you skipped a task but it turned out to apply after all).
Auto-heal on every deal page render
When you add a contact, the engine reruns the unblock check automatically against every blocked task on the deal. The contact's role is mapped to the set of stakeholder roles it can satisfy:
| Contact role | Satisfies tasks aimed at |
|---|---|
title_company or escrow_officer |
title |
buyer_agent |
buyer, agent, other_party |
seller_agent |
seller, agent, other_party |
lender |
lender |
inspector |
inspector |
So adding a single title-company contact can clear multiple title-side blockers in one move.
This same auto-heal runs after every deal page render as a safety net, in case a contact got added through a code path that didn't fire the immediate heal. You shouldn't see permanently-stuck blocked tasks once the matching contact exists.
Counter-party-satisfied tasks
One useful surprise: a task assigned to one party can be completed by a reply from a totally different party. If the listing agent writes "appraisal came in at $450k" on the deal thread, the matcher scores that line against every open task — not just the listing agent's. If the score crosses ~60% for the appraisal task, you'll see a Proposed complete card under Approvals, even though the listing agent (not the appraiser) is the one who mentioned it.
Cross-party satisfaction isn't a bug, it's a feature. Just review the proposal before confirming.
What you should NOT do
- Don't ignore a Blocked card assuming the engine will retry. It won't. Blocked is terminal until you act (or until the missing contact arrives and the heal fires).
- Don't handle it offline and leave the card in place. Use Override block or Mark complete with a reason so the audit trail stays honest.
- Don't manually flip a task back to pending from the database. Use the Reopen action in the kebab menu — it re-fires the right Inngest events so the drafter picks it up correctly.