mastra-ai/mastra · error · HTTPException

error.message (MastraError rethrown with mapped status in fa

Error message

error.message (MastraError rethrown with mapped status in failure clustering route)

What it means

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.

Source

Thrown at packages/server/src/server/handlers/datasets.ts:1496

      if (availableTags && availableTags.length > 0) {
        userMessage += `\n\nExisting tag vocabulary (prefer reusing these): ${availableTags.join(', ')}`;
      }

      if (prompt) {
        userMessage += `\n\nAdditional instructions from the reviewer: ${prompt}`;
      }

      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.`;

      const result = await clusterAgent.generate(userMessage, {
        structuredOutput: { schema: outputSchema },
      });

      const generated = await result.object;
      return { clusters: generated.clusters, proposedTags: generated.proposedTags ?? [] };
    } catch (error) {
      if (error instanceof MastraError) {
        throw new HTTPException(getHttpStatusForMastraError(error.id) as StatusCode, { message: error.message });
      }
      return handleError(error, 'Error clustering failures');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

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

Defensive patterns

Strategy: retry

Validate before calling

if (!datasetId) throw new Error('datasetId is required for clustering');

Type guard

function isMastraErrorBody(b: unknown): b is { message: string } {
  return typeof b === 'object' && b !== null && 'message' in b && typeof (b as any).message === 'string';
}

Try / catch

try {
  const res = await fetch('/api/datasets/clusters', { method: 'POST', body });
  if (res.status === 429 || res.status === 503) return retryWithBackoff();
  if (!res.ok) throw new Error(`clustering failed (${res.status})`);
} catch (err) {
  logger.error({ err }, 'failure clustering error');
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/25b770d1c82398ac. Report an issue: GitHub.