1# Browser Rendering Gotchas
2 
3## Tier Limits
4 
5| Limit | Free | Paid |
6|-------|------|------|
7| Daily browser time | 10 min | Unlimited* |
8| Concurrent sessions | 3 | 30 |
9| Requests/minute | 6 | 180 |
10| Session keep-alive | 10 min max | 10 min max |
11 
12*Subject to fair-use policy.
13 
14**Check quota:**
15```typescript
16const limits = await puppeteer.limits(env.MYBROWSER);
17// { remaining: 540000, total: 600000, concurrent: 2 }
18```
19 
20## Always Close Browsers
21 
22```typescript
23const browser = await puppeteer.launch(env.MYBROWSER);
24try {
25  const page = await browser.newPage();
26  await page.goto("https://example.com");
27  return new Response(await page.content());
28} finally {
29  await browser.close(); // ALWAYS in finally
30}
31```
32 
33**Workers vs REST:** REST auto-closes after timeout. Workers must call `close()` or session stays open until `keep_alive` expires.
34 
35## Optimize Concurrency
36 
37```typescript
38// ❌ 3 sessions (hits free tier limit)
39const browser1 = await puppeteer.launch(env.MYBROWSER);
40const browser2 = await puppeteer.launch(env.MYBROWSER);
41 
42// ✅ 1 session, multiple pages
43const browser = await puppeteer.launch(env.MYBROWSER);
44const page1 = await browser.newPage();
45const page2 = await browser.newPage();
46```
47 
48## Common Errors
49 
50| Error | Cause | Fix |
51|-------|-------|-----|
52| Session limit exceeded | Too many concurrent | Close unused browsers, use pages not browsers |
53| Page navigation timeout | Slow page or `networkidle` on busy page | Increase timeout, use `waitUntil: "load"` |
54| Session not found | Expired session | Catch error, launch new session |
55| Evaluation failed | DOM element missing | Use `?.` optional chaining |
56| Protocol error: Target closed | Page closed during operation | Await all ops before closing |
57 
58## page.evaluate() Gotchas
59 
60```typescript
61// ❌ Outer scope not available
62const selector = "h1";
63await page.evaluate(() => document.querySelector(selector));
64 
65// ✅ Pass as argument
66await page.evaluate((sel) => document.querySelector(sel)?.textContent, selector);
67```
68 
69## Performance
70 
71**waitUntil options (fastest to slowest):**
721. `domcontentloaded` - DOM ready
732. `load` - load event (default)
743. `networkidle0` - no network for 500ms
75 
76**Block unnecessary resources:**
77```typescript
78await page.setRequestInterception(true);
79page.on("request", (req) => {
80  if (["image", "stylesheet", "font"].includes(req.resourceType())) {
81    req.abort();
82  } else {
83    req.continue();
84  }
85});
86```
87 
88**Session reuse:** Cold start ~1-2s, warm connect ~100-200ms. Store sessionId in KV for reuse.
89