{"record":{"id":"ce6f6990542d824b","repo":"mastra-ai/mastra","slug":"search-failed-response-error-unknown-error","errorCode":null,"errorMessage":"Search failed: ${response.error || 'Unknown error'}","messagePattern":"Search failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/__fixtures__/fire-crawl-complex-schema.ts","lineNumber":759,"sourceCode":"Progress: ${response.completed}/${response.total}\nCredits Used: ${response.creditsUsed}\nExpires At: ${response.expiresAt}\n${response.data.length > 0 ? '\\nResults:\\n' + formatResults(response.data) : ''}`;\n        return {\n          content: [{ type: 'text', text: trimResponseText(status) }],\n          isError: false,\n        };\n      }\n\n      case 'firecrawl_search': {\n        if (!isSearchOptions(args)) {\n          throw new Error('Invalid arguments for firecrawl_search');\n        }\n        try {\n          const response = await withRetry(async () => client.search(args.query, { ...args }), 'search operation');\n\n          if (!response.success) {\n            throw new Error(`Search failed: ${response.error || 'Unknown error'}`);\n          }\n\n          const results = response.data\n            .map(\n              result =>\n                `URL: ${result.url}\nTitle: ${result.title || 'No title'}\nDescription: ${result.description || 'No description'}\n${result.markdown ? `\\nContent:\\n${result.markdown}` : ''}`,\n            )\n            .join('\\n\\n');\n\n          return {\n            content: [{ type: 'text', text: trimResponseText(results) }],\n            isError: false,\n          };\n        } catch (error) {\n          const errorMessage = error instanceof Error ? error.message : `Search failed: ${JSON.stringify(error)}`;","sourceCodeStart":741,"sourceCodeEnd":777,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/__fixtures__/fire-crawl-complex-schema.ts#L741-L777","documentation":"After calling client.search() (wrapped in withRetry), the executor checks response.success. Firecrawl v1 API returns { success: false, error: string } on failure, and this code rethrows the API's error message, defaulting to 'Unknown error' when the error field is absent. This is a server-side/API failure surfaced through the SDK response object.","triggerScenarios":"The Firecrawl search API returns success:false — invalid or missing FIRECRAWL_API_KEY, rate limiting (429), insufficient credits, Firecrawl service outage (5xx), or an invalid combination of search options rejected server-side.","commonSituations":"Expired or revoked API key; free-plan credit exhaustion; searching while Firecrawl is degraded; passing scrapeOptions the API version does not support; error field missing so the message is just 'Search failed: Unknown error'.","solutions":["Inspect response.error (or enable logging) to get the real API error message.","Verify FIRECRAWL_API_KEY is set and valid; check billing/credits on the Firecrawl dashboard.","Check https://status.firecrawl.dev for outages and retry after backoff for 429/5xx.","Confirm SDK version matches the v1 API and that search options are supported."],"exampleFix":"// before\nif (!response.success) {\n  throw new Error(`Search failed: ${response.error || 'Unknown error'}`);\n}\n// after\nif (!response.success) {\n  const msg = response.error || 'Unknown error';\n  if (/401|unauthorized/i.test(msg)) throw new Error('Check FIRECRAWL_API_KEY: ' + msg);\n  if (/429|rate/i.test(msg)) await new Promise(r => setTimeout(r, 2000)); // then retry\n  throw new Error(`Search failed: ${msg}`);\n}","handlingStrategy":"try-catch","validationCode":"// Cannot fully pre-validate (server-side), but ensure prerequisites:\nif (!process.env.FIRECRAWL_API_KEY) throw new Error('FIRECRAWL_API_KEY is not set');\nif (typeof args?.query !== 'string' || !args.query.trim()) throw new TypeError('query must be a non-empty string');","typeGuard":"function isSearchFailure(res: unknown): res is { success: false; error?: string } {\n  return typeof res === 'object' && res !== null &&\n    (res as any).success === false;\n}","tryCatchPattern":"try {\n  const res = await firecrawlSearch(args);\n  if (!res.success) throw new Error(`Search failed: ${res.error ?? 'Unknown error'}`);\n} catch (e) {\n  const msg = e instanceof Error ? e.message : String(e);\n  if (/401|403|unauthorized/i.test(msg)) throw new Error('Firecrawl auth failed - check FIRECRAWL_API_KEY');\n  if (/429|rate limit/i.test(msg)) throw new RetryableError(msg); // retry with backoff\n  throw e;\n}","preventionTips":["Keep FIRECRAWL_API_KEY set and rotate before expiry; monitor credit balance.","Wrap API calls in exponential backoff for 429/5xx.","Subscribe to Firecrawl status updates; skip calls during incidents.","Log response.error verbatim — the fallback 'Unknown error' hides the real cause."],"tags":["network","api-error","firecrawl","auth"],"backgroundTag":"api-request-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}