FAQ

When should I use browser pools vs. creating browsers on-demand?

Use browser pools when you need to run many browsers concurrently (50+ simultaneous browsers). Pools allow you to pre-configure a set of browsers for your use case, enabling you to scale to hundreds or thousands of concurrent browser sessions.

How do I know if my pool is too small or too large?

Monitor the available_count metric. If it frequently drops to 0, your pool is too small. If it stays above 30-40% of the pool size during normal operation, you’re over-provisioned. Target 10-20% available browsers during typical load.

What happens if I don’t release a browser back to the pool?

The browser will remain “acquired” until the idle timeout expires, at which point it’s destroyed and a new browser is created to refill the pool. Unreleased browsers create inefficiency and can exhaust your pool.

What is fill_rate_per_minute?

fill_rate_per_minute is the percentage of the pool that will be refilled per minute. For example, if you set fill_rate_per_minute to 10, the pool will be refilled with 10% of the pool size per minute.

When a browser from a pool is set to be destroyed (by reaching its specified timeout_seconds or reuse: false), a pool refill will be triggered to replace any destroyed browsers with new ones. Refill checks run once per minute.

Can I update a pool’s configuration without recreating it?

Yes, use kernel.browserPools.update(). By default, idle browsers are discarded and rebuilt with new configuration. Set discard_all_idle: false to only apply changes to newly created browsers.

If I update a profile’s contents, will my pool’s idle browsers pick up the change?

No. Idle browsers in a pool are pre-loaded with the profile’s contents at the time they were filled. Updating the profile (for example, re-saving auth state to the same profile_id) does not propagate to already-warmed browsers — only newly-filled browsers will use the updated profile.

To force the pool to pick up new profile contents, either call kernel.browserPools.flush() to destroy idle browsers (the pool refills automatically), or call kernel.browserPools.update() with discard_all_idle: true.

Should I set reuse: true or reuse: false when releasing?

Use reuse: true (default) for efficiency. Only use reuse: false when you suspect browser state corruption or need a guaranteed clean browser session.

How do pool timeouts interact with task duration?

The pool’s timeout_seconds only applies while the browser is acquired. If your task takes 5 minutes and timeout is 3 minutes, the browser won’t be destroyed—the timeout only triggers if the browser is idle (no CDP connection) for 3 minutes.

Can I use different browser configurations within the same pool?

All browsers in a pool initialize with the same configuration. Calling kernel.browserPools.update() updates the configuration for all idle browsers in the pool. Once you’ve acquired a browser, you can apply certain hot swap configurations to that browser instance using kernel.browsers.update().

How do I handle rate limiting from target websites?

• Implement delays between requests
• Use multiple proxy pools to distribute requests across IPs
• Implement backoff when rate limits are detected
• Consider creating separate pools with different proxy configurations

What’s the best way to debug issues in production?

• Use headless: false for a temporary debug pool, access browser_live_view_url to watch browser sessions in real-time
• Collect screenshots at error points, and maintain detailed logging around acquire/release operations
• Monitor past sessions via replays.