mastra-ai/mastra · warning · Error

No links received from Firecrawl API

Error message

No links received from Firecrawl API

What it means

After a successful map call, the executor checks `response.links`; if it is absent/falsy it throws this error because the tool has nothing to return. Firecrawl normally always returns links, so this indicates an unexpected response shape.

Source

Thrown at packages/mcp/src/__fixtures__/fire-crawl-complex-schema.ts:701

            content: [{ type: 'text', text: trimResponseText(errorMessage) }],
            isError: true,
          };
        }
      }

      case 'firecrawl_map': {
        if (!isMapOptions(args)) {
          throw new Error('Invalid arguments for firecrawl_map');
        }
        const { url, ...options } = args;
        const response = await client.mapUrl(url, {
          ...options,
        });
        if ('error' in response) {
          throw new Error(response.error);
        }
        if (!response.links) {
          throw new Error('No links received from Firecrawl API');
        }
        return {
          content: [{ type: 'text', text: trimResponseText(response.links.join('\n')) }],
          isError: false,
        };
      }

      case 'firecrawl_crawl': {
        if (!isCrawlOptions(args)) {
          throw new Error('Invalid arguments for firecrawl_crawl');
        }
        const { url, ...options } = args;
        const response = await withRetry(async () => client.asyncCrawlUrl(url, { ...options }), 'crawl operation');

        if (!response.success) {
          throw new Error(response.error);
        }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the firecrawl-js SDK version matches the live API schema and upgrade if stale.
2. Handle empty-link results gracefully in the caller instead of treating them as fatal.
3. Retry the map operation; transient truncation may explain the missing field.

Example fix

null

const res = await client.mapUrl(url, options);
if (!('links' in res) || !Array.isArray(res.links)) {
  // treat as empty result or retry rather than crashing
}

function hasLinks(r: unknown): r is { links: string[] } {
  return typeof r === 'object' && r !== null && 'links' in r && Array.isArray((r as any).links);
}

try {
  const res = await client.mapUrl(url, options);
  const links = Array.isArray(res.links) ? res.links : []; // fallback to empty
} catch (e) {
  // degrade gracefully: return empty link list with a warning
}

When it happens

Trigger: mapUrl succeeding (no `error` field) but returning a body without `links` — unexpected API version change, empty/edge-case responses for tiny or unusual sites, truncated responses.

Common situations: Using an SDK version mismatched with the current Firecrawl API response schema, mapping a site that yields zero discoverable links, proxying through a custom endpoint returning a modified payload.

Related errors

• No relevance score found in VoyageAI response
• Request failed (${res.status}) / server-provided message
• ${body.error} or Request failed (${res.status})
• Parallel ${operation} returned no output
• No Mastra units (agents, workflows, tools) found in template

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