Browser Instance icon

Browser Instance

Start and control browser instances
Join our community

Overview

This node manages browser instances programmatically within an n8n workflow. It allows users to start new browser sessions, stop existing ones (either entire browsers or specific pages), and list all active browser instances with their details.

Common scenarios include:

  • Automating web scraping or testing by starting a headless browser session.
  • Managing multiple browser instances in parallel workflows.
  • Cleaning up resources by stopping browsers or closing specific pages.
  • Monitoring active browser sessions for debugging or resource management.

Practical examples:

  • Start a headless browser to navigate and scrape data from websites.
  • Stop a browser instance after completing automated tasks to free resources.
  • List all running browsers to audit or monitor usage during workflow execution.

Properties

Name Meaning
Browser Action is: Choose the action to perform on the browser instance:
- Start Browser: Start a new browser instance or reset an existing one.
- Stop Browser: Stop a browser instance or close a specific page.
- List Browsers: List all active browser instances with their details.
Browser Name or ID Select the name of the browser instance to use. You can pick from existing eternal browsers or specify a custom ID using an expression.
Custom Browser Name Provide a unique identifier for the browser instance. This overrides the selected Browser Name. If both are empty, a default name based on the execution ID is used.
Headless Mode (Shown only when starting a browser) Run the browser in headless mode (without visible UI). Disable this option if you want to see the browser window for debugging purposes.
Page ID (Shown only when stopping a browser) Specify the ID of the page to close within the browser instance. If left empty, the entire browser instance will be closed.
Force Clean (Shown only when stopping a browser) Forcefully close the browser even if it is an eternal browser. Use with caution as this may interrupt ongoing processes.

Output

The node outputs JSON objects describing the result of the performed action:

  • For List Browsers:

    • success: Boolean indicating operation success.
    • action: The action performed ("list").
    • browsers: Array of browser objects, each containing details such as name, creation date (ISO string), and whether it is eternal.
    • count: Total number of browsers listed.
    • eternalCount: Number of eternal browsers.
    • temporaryCount: Number of temporary browsers.

  • For Start Browser:

    • success: Boolean indicating success.
    • browserName: The name/ID of the started browser instance.
    • pageId: Empty string (no page specified at start).
    • action: The action performed ("start").
    • message: Confirmation message.

  • For Stop Browser:

    • success: Boolean indicating success or failure of the stop/close operation.
    • browserName: The name/ID of the stopped browser instance.
    • pageId: The page ID that was closed (if applicable).
    • action: The action performed ("stop").
    • forceClean: Boolean indicating if force clean was applied.
    • message: Status message about the stop or page close operation.

If the node encounters errors and "Continue On Fail" is enabled, the output JSON will contain an error field with the error message.

The node does not output binary data.

Dependencies

  • Requires access to a browser management system abstracted by the BrowserWheelBook class, which handles browser lifecycle operations.
  • No direct external API keys or credentials are required, but the environment should support launching and managing browser instances.
  • The node respects the NODE_ENV environment variable to determine default headless mode behavior (true in production, false otherwise).

Troubleshooting

  • Error starting browser instance: Could occur if the browser cannot be launched or reset. Check system resources and permissions.
  • Error stopping browser instance: May happen if the specified browser or page ID does not exist or is already closed.
  • Page not found in eternal browser: When trying to close a page that does not exist in the specified eternal browser.
  • Force Clean caution: Using force clean stops browsers abruptly; ensure no critical tasks are running to avoid data loss.
  • If the node fails unexpectedly, enabling "Continue On Fail" allows the workflow to proceed while capturing error messages in output.

Links and References

  • n8n Expressions Documentation
  • General browser automation concepts (e.g., Puppeteer or Playwright documentation) may help understand browser instance management.

Discussion