{"record":{"id":"25b770d1c82398ac","repo":"mastra-ai/mastra","slug":"error-message-mastraerror-rethrown-with-mapped-st-25b770","errorCode":null,"errorMessage":"error.message (MastraError rethrown with mapped status in failure clustering route)","messagePattern":"error\\.message \\(MastraError rethrown with mapped status in failure clustering route\\)","errorType":"http","errorClass":"HTTPException","httpStatus":null,"severity":"error","filePath":"packages/server/src/server/handlers/datasets.ts","lineNumber":1496,"sourceCode":"      if (availableTags && availableTags.length > 0) {\n        userMessage += `\\n\\nExisting tag vocabulary (prefer reusing these): ${availableTags.join(', ')}`;\n      }\n\n      if (prompt) {\n        userMessage += `\\n\\nAdditional instructions from the reviewer: ${prompt}`;\n      }\n\n      userMessage += `\\n\\nReturn both \"clusters\" (grouping items by pattern) and \"proposedTags\" (a list mapping each item ID to the tag labels you recommend, with a \"reason\" explaining why). For proposedTags, only include NEW tags to add — do not repeat tags the item already has.`;\n\n      const result = await clusterAgent.generate(userMessage, {\n        structuredOutput: { schema: outputSchema },\n      });\n\n      const generated = await result.object;\n      return { clusters: generated.clusters, proposedTags: generated.proposedTags ?? [] };\n    } catch (error) {\n      if (error instanceof MastraError) {\n        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });\n      }\n      return handleError(error, 'Error clustering failures');\n    }\n  },\n});\n","sourceCodeStart":1478,"sourceCodeEnd":1502,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/datasets.ts#L1478-L1502","documentation":"The failure-clustering route runs a structured (object) generation that clusters agent failures and proposes tags. If that pipeline throws a MastraError, the route rethrows it as an HTTPException with a status code mapped from the error id via getHttpStatusForMastraError, passing error.message through unchanged to the client. Non-MastraError failures fall through to handleError.","triggerScenarios":"Calling the failure-clustering endpoint when the clustering LLM call throws a MastraError — e.g. invalid model response failing structured-output schema, provider outage, or rate-limit domain errors from the generation layer.","commonSituations":"Model returns output that does not match the clusters/proposedTags schema, LLM provider returns 429/5xx which surfaces as a MastraError, or the clustering agent is misconfigured in the mastra instance; user sees a mapped HTTP status with the raw model/workflow error text.","solutions":["Inspect error.message and the mapped status to identify the failing domain","Retry with backoff if the status maps to 429/503 (provider throttling)","Validate that the clustering agent/model configuration and output schema are correct","Log the full MastraError id server-side if the message alone is insufficient"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if (!datasetId) throw new Error('datasetId is required for clustering');","typeGuard":"function isMastraErrorBody(b: unknown): b is { message: string } {\n  return typeof b === 'object' && b !== null && 'message' in b && typeof (b as any).message === 'string';\n}","tryCatchPattern":"try {\n  const res = await fetch('/api/datasets/clusters', { method: 'POST', body });\n  if (res.status === 429 || res.status === 503) return retryWithBackoff();\n  if (!res.ok) throw new Error(`clustering failed (${res.status})`);\n} catch (err) {\n  logger.error({ err }, 'failure clustering error');\n}","preventionTips":["Add backoff retry for transient provider statuses (429/503)","Verify structured-output schema for clusters/proposedTags matches the model's capabilities","Keep model credentials/config validated before invoking clustering"],"tags":["server","http","error-mapping","clustering","ai"],"backgroundTag":"mastra-error-rethrow","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}