{"record":{"id":"1c32971bcb4ea249","repo":"n8n-io/n8n","slug":"agentlabel-reason","errorCode":null,"errorMessage":"${agentLabel} ${reason}","messagePattern":"\\$\\{agentLabel\\} \\$\\{reason\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@n8n/instance-ai/src/stream/consume-with-hitl.ts","lineNumber":67,"sourceCode":"\t/** Accumulated tool call outcomes observed during stream consumption. */\n\tworkSummary: WorkSummary;\n}\n\nexport async function requireCompletedHitlText(\n\tresult: ConsumeWithHitlResult,\n\tagentLabel: string,\n): Promise<string> {\n\tif (result.status === 'completed') {\n\t\treturn await result.text;\n\t}\n\n\tconst reason =\n\t\tresult.status === 'cancelled'\n\t\t\t? 'was cancelled'\n\t\t\t: result.status === 'errored'\n\t\t\t\t? 'failed while streaming'\n\t\t\t\t: `ended with unexpected status \"${result.status}\"`;\n\tthrow new Error(`${agentLabel} ${reason}`);\n}\n\n/**\n * Consume a sub-agent stream with HITL suspend/resume support.\n * Detects `tool-call-suspended` chunks, waits for user confirmation,\n * and resumes the stream. Used by delegate, builder, and other agent tools.\n *\n * Returns `{ text }` — a promise for the agent's full text output.\n * When HITL occurred, this returns the resumed stream's text (not the original).\n */\nexport async function consumeStreamWithHitl(\n\toptions: ConsumeWithHitlOptions,\n): Promise<ConsumeWithHitlResult> {\n\tif (!options.waitForConfirmation) {\n\t\tthrow new Error('Sub-agent tool requires confirmation but no HITL handler is available');\n\t}\n\n\tconst stream = normalizeStreamSource(options.stream);","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/instance-ai/src/stream/consume-with-hitl.ts#L49-L85","documentation":"Thrown by requireCompletedHitlText (consume-with-hitl.ts:53-68) when a sub-agent stream result is not 'completed'. The status is mapped to a reason: 'cancelled' -> 'was cancelled', 'errored' -> 'failed while streaming', anything else -> a literal 'unexpected status' message. The agentLabel is interpolated to identify which sub-agent failed. This is a post-stream consumer check, not a streaming-layer failure.","triggerScenarios":"A sub-agent (delegate/builder/etc.) stream returns with result.status of 'cancelled' or 'errored', or a status the consumer does not recognize. The caller invoked consumeStreamWithHitl and then requireCompletedHitlText on the result.","commonSituations":"Sub-agent was aborted (cancelled); the underlying LLM call failed (errored); a resume produced an unexpected terminal status; the sub-agent hit its iteration limit and returned a non-completed status.","solutions":["Inspect the underlying stream/trace for why the sub-agent reported cancelled or errored.","If cancelled by an abort, retry the parent operation once the abort source is resolved.","Check agent logs and the workSummary for the error chunk that caused 'errored'.","If the status is genuinely unknown, report it as a bug — only 'completed' is considered success."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before calling requireCompletedHitlText, inspect the result status:\nif (result.status !== 'completed') {\n  throw new Error(`${agentLabel} ended with status ${result.status}`);\n}","typeGuard":"function isCompletedResult(r: { status: string }): r is { status: 'completed' } {\n  return r.status === 'completed';\n}","tryCatchPattern":"try { return await requireCompletedHitlText(result, agentLabel); }\ncatch (e) {\n  if (e instanceof Error && e.message.includes(agentLabel)) {\n    // inspect result.workSummary / trace for the underlying cancel/error cause\n  }\n  throw e;\n}","preventionTips":["Check the trace and workSummary when a sub-agent reports cancelled/errored.","Confirm the abort signal was not tripped unintentionally.","Treat only 'completed' as success; surface other statuses to the caller."],"tags":["hitl","sub-agent","streaming","status","consumer"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}