{"record":{"id":"42819e13d66c9dd5","repo":"mastra-ai/mastra","slug":"apierror-message-defaultmessage-fallback-handl","errorCode":null,"errorMessage":"apiError.message || defaultMessage (fallback handler error)","messagePattern":"apiError\\.message \\|\\| defaultMessage \\(fallback handler error\\)","errorType":"http","errorClass":"HTTPException","httpStatus":null,"severity":"error","filePath":"packages/server/src/server/handlers/error.ts","lineNumber":136,"sourceCode":"      message: error.message,\n      stack: error.stack,\n      cause: error,\n    });\n  }\n\n  if (isWorkflowSchemaValidationError(error)) {\n    throw new HTTPException(400, {\n      message: error.message,\n      stack: error.stack,\n      cause: error,\n    });\n  }\n\n  const apiError = error as ApiError;\n\n  const apiErrorStatus = apiError.status || apiError.details?.status || 500;\n\n  throw new HTTPException(apiErrorStatus as StatusCode, {\n    message: apiError.message || defaultMessage,\n    stack: apiError.stack,\n    cause: apiError.cause,\n  });\n}\n","sourceCodeStart":118,"sourceCodeEnd":142,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/error.ts#L118-L142","documentation":"This is the fallback branch of handleError: when the thrown error is not one of the recognized special cases, it is cast to ApiError and rethrown as HTTPException using apiError.status or apiError.details.status (defaulting to 500), with apiError.message or the caller-supplied defaultMessage. The library throws this to give every unhandled handler error a consistent HTTP shape while preserving the original message, stack, and cause.","triggerScenarios":"Any of the agent-builder routes (LIST/GET actions, LIST/GET runs, CREATE run, STREAM run) throws an unrecognized Error; or an ApiError without a message is thrown so the route's defaultMessage is used.","commonSituations":"An upstream/core error without a status surfaces as an opaque 500; a thrown string or non-Error object has no .message so the generic defaultMessage is returned; storage or network failures inside a handler bubble up unclassified.","solutions":["Check the response status and message; if it's 500, inspect server logs and the error.cause for the underlying fault.","Ensure code that intends a specific HTTP status throws errors with a `status` (or `details.status`) property so the correct code is preserved.","Always throw Error instances with a meaningful message instead of strings or bare objects, so clients get actionable text rather than defaultMessage.","If a recognized error is being misclassified, verify its identifying fields (code / id) are set as handleError expects."],"exampleFix":"// before: thrown string becomes a generic 500 with defaultMessage\nthrow 'run failed';\n// after: throw a structured ApiError with status and message\nconst err = new Error('run failed: model unavailable') as Error & { status: number };\nerr.status = 503;\nthrow err;","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function hasStatus(e: unknown): e is Error & { status: number } {\n  return e instanceof Error && typeof (e as any).status === 'number';\n}","tryCatchPattern":"try {\n  const actions = await listAgentBuilderActions();\n} catch (e) {\n  const status = (e as any)?.status ?? (e as any)?.details?.status ?? 500;\n  if (status >= 500) {\n    logError('server fault in agent-builder route', { cause: (e as any)?.cause });\n    return retryWithBackoff(() => listAgentBuilderActions());\n  }\n  throw e;\n}","preventionTips":["Always throw Error objects with a message and an explicit status for intended HTTP codes.","Attach `cause` when rethrowing so server logs and clients can trace the root fault.","Monitor 500 rates on agent-builder routes; an unclassified error usually means a missing branch in handleError."],"tags":["http-500","api-error","error-handling"],"backgroundTag":"unhandled-server-error","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}