{"record":{"id":"b03edc0dc6ee7582","repo":"mastra-ai/mastra","slug":"metadata-errormessage-workflow-execution-fa","errorCode":null,"errorMessage":"${metadata?.errorMessage || 'Workflow execution failed'}","messagePattern":"\\$\\{metadata\\?\\.errorMessage \\|\\| 'Workflow execution failed'\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/react/src/workflows/use-stream-workflow.ts","lineNumber":115,"sourceCode":"        return;\n      }\n      const error = err instanceof Error ? err : new Error(defaultMessage);\n      onError?.(error, defaultMessage);\n      setStreamingState?.(false);\n    },\n    [onError],\n  );\n\n  const handleWorkflowFinish = useCallback((value: StreamVNextChunkType) => {\n    if (value.type === 'workflow-finish') {\n      const streamStatus = value.payload?.workflowStatus;\n      const metadata = value.payload?.metadata;\n      setStreamResult(prev => ({\n        ...prev,\n        status: streamStatus,\n      }));\n      if (streamStatus === 'failed') {\n        throw new Error(metadata?.errorMessage || 'Workflow execution failed');\n      }\n      // Tripwire status is not an error - it's handled separately in the UI\n      // Don't throw an error for tripwire status\n    }\n  }, []);\n\n  const streamWorkflow = useMutation<void, Error, StreamWorkflowParams>(\n    async ({ workflowId, runId, inputData, initialState, requestContext: playgroundRequestContext, perStep }) => {\n      // Clean up any existing reader before starting new stream\n      if (readerRef.current) {\n        readerRef.current.releaseLock();\n      }\n\n      if (!isMountedRef.current) return;\n\n      setIsStreaming(true);\n      setStreamResult({ input: inputData } as WorkflowStreamResult);\n      const workflow = client.getWorkflow(workflowId);","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/react/src/workflows/use-stream-workflow.ts#L97-L133","documentation":"useStreamWorkflow's observer throws this when the workflow stream reports status 'failed'. The metadata payload of the failure event may carry an errorMessage, which is used as the message; otherwise the generic 'Workflow execution failed' is used. It converts an async stream termination state into a thrown error so React consumers (and React Query-style error handling) see it as a failure.","triggerScenarios":"Streaming a workflow whose run transitions to status 'failed' — e.g. a step threw, the workflow's error handler re-threw, or the engine aborted the run. Observed inside the stream-value observer in useStreamWorkflow.","commonSituations":"A workflow step raised an unhandled exception; input schema validation failed server-side; resume/timeTravel hit a broken run; transient storage or network failure during the run.","solutions":["Read metadata.errorMessage / the thrown message to find the failing step, then fix the bug in the workflow step","Inspect the workflow run's trace/logs in Mastra Studio for the root cause","Wrap your usage of the hook's stream in error handling and surface retry/resume UX","Check that resume/timeTravel is only called on runs in a compatible state"],"exampleFix":"// before\nconst { streamResult } = useStreamWorkflow({ workflowId }); // error surfaces unhandled\n// after\nuseEffect(() => {\n  if (error) console.error('Workflow failed:', error.message); // show retry UI\n}, [error]);","handlingStrategy":"try-catch","validationCode":"// check workflow run status before/after streaming\nif (streamResult?.status === 'failed') {\n  console.error('Workflow failed:', streamResult?.metadata?.errorMessage);\n}","typeGuard":"function isFailedEvent(value: unknown): value is { type: 'workflow-update'; payload: { metadata?: { errorMessage?: string } } } {\n  return typeof value === 'object' && value !== null && (value as any).type === 'workflow-update';\n}","tryCatchPattern":"try {\n  await observeWorkflowStream();\n} catch (err) {\n  if (err instanceof Error && /Workflow execution failed/.test(err.message)) {\n    showError(err.message); // offer resume/retry\n  } else throw err;\n}","preventionTips":["Add error handling inside workflow steps so failures carry a clear errorMessage in metadata","Monitor run status in Studio traces to catch failing steps early","Validate workflow input schemas client-side before starting the stream","Implement retry/resume UI for failed statuses instead of letting errors escape"],"tags":["workflow","streaming","react"],"backgroundTag":"workflow-execution-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}