firecrawl/open-lovable · error · Error

Failed to capture screenshot

Error message

Failed to capture screenshot

What it means

The route's generic failure error for screenshot scraping: thrown when the Firecrawl scrape result reports `success === false` and its `error` field is empty, so no specific upstream reason is available. It indicates Firecrawl processed the request but could not produce a result.

Source

Thrown at app/api/scrape-screenshot/route.ts:64

    // Check if we have data with screenshot
    if (scrapeResult && scrapeResult.screenshot) {
      // Direct screenshot response
      return NextResponse.json({
        success: true,
        screenshot: scrapeResult.screenshot,
        metadata: scrapeResult.metadata || {}
      });
    } else if ((scrapeResult as any)?.data?.screenshot) {
      // Nested data structure
      return NextResponse.json({
        success: true,
        screenshot: (scrapeResult as any).data.screenshot,
        metadata: (scrapeResult as any).data.metadata || {}
      });
    } else if ((scrapeResult as any)?.success === false) {
      // Explicit failure
      console.error('[scrape-screenshot] Firecrawl API error:', (scrapeResult as any).error);
      throw new Error((scrapeResult as any).error || 'Failed to capture screenshot');
    } else {
      // No screenshot in response
      console.error('[scrape-screenshot] No screenshot in response. Full response:', JSON.stringify(scrapeResult, null, 2));
      throw new Error('Screenshot not available in response - check console for full response structure');
    }

  } catch (error: any) {
    console.error('[scrape-screenshot] Screenshot capture error:', error);
    console.error('[scrape-screenshot] Error stack:', error.stack);
    
    // Provide fallback response for development - removed NODE_ENV check as it doesn't work in Next.js production builds
    
    return NextResponse.json({ 
      error: error.message || 'Failed to capture screenshot'
    }, { status: 500 });
  }
}

View on GitHub (pinned to 69bd93bae7)

Solutions

  1. Retry the scrape once — many failures are transient rendering timeouts
  2. Check the target URL is publicly reachable, http(s), and doesn't require login
  3. Inspect Firecrawl dashboard/plan limits if failures persist (blocked domains, quota)
  4. Log the full scrapeResult when success===false so the upstream error text isn't lost

Example fix

// before
} else if ((scrapeResult as any)?.success === false) {
  throw new Error((scrapeResult as any).error || 'Failed to capture screenshot');
}
// after
} else if ((scrapeResult as any)?.success === false) {
  console.error('[scrape-screenshot] full result:', JSON.stringify(scrapeResult));
  throw new Error((scrapeResult as any).error || 'Failed to capture screenshot');
}
Defensive patterns

Strategy: retry

Validate before calling

const u = new URL(url);
if (!/^https?:$/.test(u.protocol)) throw new Error('Only public http(s) pages can be screenshotted');

Type guard

function scrapeFailed(r: any): r is { success: false; error?: string } {
  return r?.success === false;
}

Try / catch

try {
  return await captureScreenshot(url);
} catch (e) {
  if (e.message === 'Failed to capture screenshot') {
    await sleep(1500);
    return captureScreenshot(url); // transient render failures often succeed on retry
  }
  throw e;
}

Prevention

When it happens

Trigger: POST /api/scrape-screenshot where Firecrawl's response has `success: false` with a null/undefined `error` property — e.g. target page timed out, was blocked (403/captcha), or screenshot capture failed internally at Firecrawl.

Common situations: Scraping sites that block bots or require JS/login; screenshot format unsupported for the URL scheme (non-http URL); Firecrawl internal errors during rendering; transient network failures at scrape time.

Related errors

AI-assisted analysis of firecrawl/open-lovable@69bd93bae7 (2026-08-28). Data as JSON: /api/errors/a64130f045432cd8. Report an issue: GitHub.