{"record":{"id":"396f2dcf5b0fcfab","repo":"mastra-ai/mastra","slug":"tripwirechunk-payload-reason-agent-tripwire","errorCode":null,"errorMessage":"${tripwireChunk.payload?.reason || 'Agent tripwire triggered'}","messagePattern":"\\$\\{tripwireChunk\\.payload\\?\\.reason \\|\\| 'Agent tripwire triggered'\\}","errorType":"exception","errorClass":"TripWire","httpStatus":null,"severity":"warning","filePath":"packages/core/src/workflows/entry-executors/run-agent-entry.ts","lineNumber":130,"sourceCode":"    // throws inside the base output's try/catch (see output.ts:970-973,978-981)\n    // and it fires BEFORE handleFinish, so racing here would poison\n    // streamPromise. Only the rejection channel below is wired up so genuine\n    // stream errors still propagate.\n    void modelOutput.text.then(\n      () => {},\n      (err: unknown) => streamPromise.reject(err),\n    );\n    stream = modelOutput.fullStream as ReadableStream<ChunkType>;\n  }\n\n  const tripwireChunk =\n    streamFormat === 'legacy'\n      ? await bridgeLegacyWatchEvents({ stream, pubsub, runId, toolData })\n      : await consumeStreamForTripwire(stream, writer);\n\n  // If a tripwire was detected, throw TripWire to abort the workflow step\n  if (tripwireChunk) {\n    throw new TripWire(\n      tripwireChunk.payload?.reason || 'Agent tripwire triggered',\n      {\n        retry: tripwireChunk.payload?.retry,\n        metadata: tripwireChunk.payload?.metadata,\n      },\n      tripwireChunk.payload?.processorId,\n    );\n  }\n\n  if (abortSignal.aborted) {\n    return abort();\n  }\n\n  // Return structured output if available, otherwise default text\n  if (structuredResult !== null) {\n    return structuredResult;\n  }\n  return {","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/entry-executors/run-agent-entry.ts#L112-L148","documentation":"While streaming an agent step, the workflow consumes the stream watching for tripwire chunks emitted by input/output processors. If a tripwire is detected, runAgentEntry throws a TripWire (not a plain Error) carrying the processor-provided reason, retry, metadata, and processorId, to abort the workflow step.","triggerScenarios":"An agent stream inside a workflow step emits a tripwire chunk — typically an input or output processor (e.g. moderation, guardrails) flagged the prompt or response — with streamFormat legacy or vnext handled via consumeStreamForTripwire.","commonSituations":"Content moderation / guardrail processors rejecting user input; custom output processors aborting on policy violations; users testing with prompts that trip configured safety processors.","solutions":["Inspect TripWire.reason and processorId to identify which processor tripped and why.","Adjust or remove the offending processor configuration on the agent if the trip is a false positive.","Handle TripWire in your workflow error handling (it is distinct from Error) — catch it and branch or retry as appropriate.","Use the TripWire retry/metadata payload to decide whether to retry the step."],"exampleFix":"// before\nawait wf.run({ input }); // unhandled TripWire aborts run\n// after\ntry { await wf.run({ input }); }\ncatch (e) { if (e instanceof TripWire) { console.warn('Tripped by', e.processorId, e.reason); } else throw e; }","handlingStrategy":"try-catch","validationCode":"const processors = agent?.inputProcessors ?? [];\nif (processors.some(p => p?.id === 'strict-moderation')) {\n  // pre-screen input before running the workflow step\n  if (await violatesPolicy(input)) throw new PolicyError('Input would trip moderation processor');\n}","typeGuard":"import { TripWire } from '@mastra/core/workflows';\nfunction isTripWire(e: unknown): e is TripWire {\n  return e instanceof TripWire;\n}","tryCatchPattern":"try { await runWorkflow(input); }\ncatch (e) {\n  if (e instanceof TripWire) {\n    logger.warn({ reason: e.reason, processorId: e.processorId, metadata: e.metadata }, 'workflow tripped');\n    return { status: 'blocked', reason: e.reason };\n  }\n  throw e;\n}","preventionTips":["Always catch TripWire separately from Error in workflow runners.","Log TripWire.processorId to identify offending processors quickly.","Test agent processors against edge-case inputs before production.","Surface tripwire reasons to end users instead of generic 500s."],"tags":["workflows","agents","tripwire","processors","streaming"],"backgroundTag":"guardrail-tripwire","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}