CDP Request Timeout in ego-lite: Default Duration and Configuration

The default CDP request timeout in ego-lite is 30 seconds (30,000 ms), after which the runtime rejects the promise with a "CDP request timed out" error.

The citrolabs/ego-lite library provides a lightweight browser automation layer built on the Chrome DevTools Protocol (CDP). Understanding the CDP request timeout behavior is essential for handling long-running operations or network latency in your automation scripts, as the default limit is enforced in the core browser runtime.

Default 30-Second Timeout in browser-runtime.ts

The timeout value is hardcoded in the low-level browser runtime. In src/browser-runtime.ts, the internal sendCDPMessage function wraps every CDP command with a default timer of 30,000 milliseconds. If the Chrome DevTools Protocol peer fails to respond within this window, the runtime reaches line 57 and executes reject(new Error(\CDP request timed out: ${method}`));`, terminating the pending operation with a clear error signature.

How sendCDPMessage Implements the Timeout

The implementation relies on the modern AbortSignal.timeout(timeoutMs) API, where timeoutMs defaults to 30000 when no explicit duration is provided. This signal aborts the underlying network operation if the CDP endpoint remains silent, preventing zombie requests from blocking the automation queue indefinitely.

Per-Call Override Mechanism

While the global default is 30 seconds, individual CDP calls can specify custom durations via the timeout parameter in the options object. This allows fine-grained control for operations like network emulation or large file downloads that naturally exceed the standard limit.

Practical Code Examples

The following examples demonstrate both the default behavior and custom timeout overrides using the cdp() helper exposed by the runtime.

// Default 30-second timeout applied automatically
await cdp('Runtime.evaluate', { 
  expression: 'document.title' 
});

// Extending timeout to 60 seconds for slow network operations
await cdp('Network.enable', { 
  timeout: 60_000 
});

// Short 5-second timeout for rapid existence checks
await cdp('DOM.querySelector', {
  nodeId: rootId,
  selector: '#submit-button',
  timeout: 5_000
});

// High-level helpers inherit the same timeout behavior
await pointer.click('#checkout'); // Uses default 30s unless overridden

Error Handling When Timeouts Expire

When the threshold is exceeded, the rejected promise carries an Error object with the exact message format CDP request timed out: ${method}. You should wrap CDP calls in try-catch blocks to handle these failures gracefully, particularly in CI environments with variable latency or when interacting with resource-constrained targets.

Related Source Files and Architecture

• src/browser-runtime.ts – Contains the sendCDPMessage function and the 30000 ms default constant. Line 57 generates the timeout error message.
• src/cdp-eval.ts – Public API surface that forwards CDP calls to the browser runtime, accepting the optional timeout parameter.
• src/driver/waits.ts – Propagates timeout values into CDP-based waiting utilities for element selection and navigation events.
• src/helpers.ts – Exposes high-level automation primitives (like pointer.click and js()) that ultimately rely on the underlying CDP timeout mechanism.

Summary

• The default CDP request timeout in ego-lite is 30 seconds (30,000 ms).
• The limit is defined in src/browser-runtime.ts within the sendCDPMessage implementation.
• The mechanism uses AbortSignal.timeout(30000) to abort stalled requests.
• Developers can override the default per-request by passing a timeout property in milliseconds.
• Expired requests reject with the error message CDP request timed out: ${method}.

Frequently Asked Questions

What is the default CDP request timeout in ego-lite?

The default timeout is 30 seconds (30,000 milliseconds). This value is hardcoded in the browser runtime and applies to all Chrome DevTools Protocol requests unless explicitly overridden.

How can I override the timeout for a specific CDP command?

Pass a timeout property in the options object when calling cdp() or related helpers. For example: await cdp('Network.enable', { timeout: 60_000 }); extends the limit to 60 seconds for that specific operation.

What error message appears when a CDP request times out?

The runtime rejects the promise with an Error object containing the message CDP request timed out: ${method}, where method is the specific CDP command that failed (e.g., Runtime.evaluate).

Where is the timeout logic implemented in the source code?

The logic resides in src/browser-runtime.ts. The sendCDPMessage function manages the timer, and line 57 specifically handles the rejection with the timeout error message. The default value of 30000 ms is used when the timeout parameter is omitted from the call.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}