Skip to main content

Built-in Queueing System

Browserless includes a built-in queueing system that manages browser concurrency and request flow. The system prevents your infrastructure from being overwhelmed by too many simultaneous browser instances.

How the Queueing System Works​

Browserless implements a three-tier system to manage browser requests:

Concurrency Limit​

When you start a browser session, the system checks if you are within your concurrency limit. If you are, the browser starts immediately.

Queueing​

Once you exceed your concurrency limit, new requests enter a queue instead of being rejected. The system processes queued requests in order as browser slots become available.

Request Rejection​

If your queue is full, new requests are rejected with an error message. This prevents system overload and allows existing requests to complete.

Why Proper Browser Cleanup Matters​

The queueing system relies on browsers being properly closed to free up slots for queued requests. When browsers aren't closed correctly, they continue consuming resources until they hit the default timeout, which can cause unnecessary delays for other requests.

The Problem with Hanging Browsers​

When browsers are left open without proper cleanup:

  • Resource Waste: Each hanging browser continues consuming CPU and memory
  • Queue Delays: Queued requests must wait longer for slots to become available
  • Timeout Issues: Browsers may hit navigation timeouts due to resource constraints
  • Reduced Throughput: Fewer requests can be processed efficiently

Best Practices for Browser Management​

To ensure optimal performance and prevent hanging browsers:

  • Always close browsers when done: Call browser.close() when your task completes
  • Handle errors gracefully: Close browsers even when errors occur to free up resources
  • Set reasonable timeouts: Configure appropriate timeout values for your use case (defaults may be too high)
  • Monitor your usage: Keep track of your concurrency and queue limits

Concurrency and Worker Health​

Health Check Options​

Enable health check options in your worker settings to verify machine health before starting a new browser. When resources are insufficient, the system rejects the request instead of starting a browser that would time out.

Managing Concurrency for High Resource Usage​

If you experience frequent timeouts when running many requests, reduce your max concurrency in worker settings. This limits how many browsers run simultaneously per machine.

For high CPU/memory workloads, run fewer browsers per machine by reducing concurrency or using larger machines. Lower concurrency gives each browser more CPU and memory, reduces timeouts, and improves stability.

Start with a conservative concurrency setting and adjust based on your performance metrics.

Configuring Queue Behavior​

Self-Hosted Docker​

Set concurrency and queue limits via environment variables:

  • CONCURRENT: Maximum concurrent browser sessions (default: 10)
  • QUEUED: Maximum queued requests before returning 429 (default: 10)
  • TIMEOUT: Session timeout in milliseconds (default: 30000)

See the Configuration Reference for all options.

Private Deployment (Managed)​

Adjust concurrency and queue limits from your account dashboard under Settings. See Worker Settings for details.