{"record":{"id":"a48f39bc300f3ac2","repo":"mastra-ai/mastra","slug":"response-error-deep-research-failed","errorCode":null,"errorMessage":"${response.error || 'Deep research failed'}","messagePattern":"\\$\\{response\\.error \\|\\| 'Deep research failed'\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/__fixtures__/fire-crawl-complex-schema.ts","lineNumber":868,"sourceCode":"          const response = await client.deepResearch(\n            args.query as string,\n            {\n              maxDepth: args.maxDepth as number,\n              timeLimit: args.timeLimit as number,\n              maxUrls: args.maxUrls as number,\n            },\n            activity => {\n              safeLog('info', `Research activity: ${activity.message} (Depth: ${activity.depth})`);\n            },\n            source => {\n              safeLog('info', `Research source found: ${source.url}${source.title ? ` - ${source.title}` : ''}`);\n            },\n          );\n\n          safeLog('info', `Deep research completed in ${Date.now() - researchStartTime}ms`);\n\n          if (!response.success) {\n            throw new Error(response.error || 'Deep research failed');\n          }\n\n          const formattedResponse = {\n            finalAnalysis: response.data.finalAnalysis,\n            activities: response.data.activities,\n            sources: response.data.sources,\n          };\n\n          return {\n            content: [\n              {\n                type: 'text',\n                text: trimResponseText(formattedResponse.finalAnalysis),\n              },\n            ],\n            isError: false,\n          };\n        } catch (error) {","sourceCodeStart":850,"sourceCodeEnd":886,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/__fixtures__/fire-crawl-complex-schema.ts#L850-L886","documentation":"After the deep research job finishes, the executor checks response.success and throws the API's error message, defaulting to 'Deep research failed'. Deep research runs scraping + analysis steps server-side at Firecrawl, so failures include per-page scrape failures aggregated into the job as well as auth/credit/limit issues.","triggerScenarios":"response.success is false when the research job completes or fails — invalid API key, credit exhaustion mid-job, rate limiting during the many underlying scrape/search calls, or all target pages failing to scrape.","commonSituations":"Long research jobs hitting credit limits before completion; Firecrawl service degradation during an expensive multi-step job; transient 429s not retried by the outer withRetry because the job already returned success:false.","solutions":["Surface response.error to identify whether it was auth, credits, rate limit, or scrape failures.","Reduce job scope (lower maxUrls/maxDepth/timeLimit) to lower cost and failure probability.","Confirm API key and credit balance; upgrade plan if deep research is credit-hungry.","Retry with backoff for transient 429/5xx causes, and check Firecrawl status for outages."],"exampleFix":"// before\nif (!response.success) {\n  throw new Error(response.error || 'Deep research failed');\n}\n// after\nif (!response.success) {\n  const detail = response.error || 'no error detail returned';\n  if (/credit|quota/i.test(detail)) throw new Error('Firecrawl credits exhausted: ' + detail);\n  if (/rate limit/i.test(detail)) throw new RetryableError(detail);\n  throw new Error(`Deep research failed: ${detail}`);\n}","handlingStrategy":"retry","validationCode":"// Budget pre-check to reduce mid-job failures:\nif (!args?.query) throw new TypeError('query required');\nif ((args.maxUrls ?? Infinity) * (args.maxDepth ?? Infinity) > 500) {\n  console.warn('Deep research job may be credit-expensive; consider lowering maxUrls/maxDepth');\n}","typeGuard":"function isDeepResearchSuccess(res: unknown): res is { success: true; data: { finalAnalysis: string; activities?: unknown[]; sources?: unknown[] } } {\n  return typeof res === 'object' && res !== null && (res as any).success === true && !!res.data?.finalAnalysis;\n}","tryCatchPattern":"try {\n  const res = await firecrawlDeepResearch(args);\n  if (!res.success) throw new Error(res.error || 'Deep research failed');\n} catch (e) {\n  const msg = e instanceof Error ? e.message : String(e);\n  if (/rate limit|429|temporarily/i.test(msg)) return withBackoff(() => firecrawlDeepResearch(smallerScope(args)), 3);\n  if (/credit|quota/i.test(msg)) throw new Error('Insufficient Firecrawl credits for deep research');\n  throw e;\n}","preventionTips":["Scope jobs conservatively (maxUrls, maxDepth, timeLimit) to avoid credit exhaustion mid-run.","Retry only transient failures; auth/credit errors need human action.","Monitor Firecrawl status page before long research jobs.","Persist response.error details for post-mortem rather than the generic fallback."],"tags":["network","api-error","firecrawl","long-running-job"],"backgroundTag":"api-request-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}