Configure and Manage the Bridge Client Pool

This topic describes how site admins can configure and manage pooling for Bridge clients. Pooling allows clients across the site to load balance data freshness tasks for data sources that connect to on-premises data.

Configure pooling

The purpose of a pool is to distribute (or load balance) data freshness tasks among the available clients in a pool. Although the client in the pool that performs the data freshness task is chosen at random, if for whatever reason a client can no longer perform the task, the task is automatically rerouted to another available client in the pool to handle the task. There is no additional intervention required from you or your users to support or manage the pool of clients.

Pooling is optimized for keeping data sources that connect to relational data fresh. Pooling support does not extend to data sources that use Bridge (legacy) schedules or connect to file data because for those cases, the scheduled refresh must be associated with a specific client.

In general, we recommend pooling in the following situations:

  • Bridge is used as a critical service. If your organization requires that live query and scheduled refresh support must be available even if a client becomes unavailable.

  • Client is at capacity. If your existing site traffic is exceeding current capacity of the client.

Before configuring the pool

Before you can configure the client pool for the site, review the following:

  • (Required) Clients must be installed and running.
  • Clients are configured to run as a service. For more information, see Application versus Service mode.
  • The user authenticated into the client is a Tableau Online site admin. For more information about deploying Bridge, see Plan Your Bridge Deployment.

Note: Prior to Bridge 2020.2, only live queries could be pooled. Scheduled refreshes for extracts could not be pooled.

Note about user roles

Only site admins, or users with either the Site Administrator or Site Administrator Creator role, can configure and maintain pooled clients. Regardless of the type of user authenticated in to the client, only site admins can add clients to the pool, remove clients from the pool, and monitor clients in the pool.

Step 1: Ensure clients can connect to the site

In order for Bridge to work with your site, you must allow clients to authenticate to the site.

  1. Sign in to Tableau Online using your site admin credentials and go to the Settings page.

  2. Click the Authentication tab and validate that the Let clients automatically connect to this Tableau Online site check box under the Connected Clients heading is selected. For more information about this check box, see Access Sites from Connected Clients.

Step 2: Enable pooling

In addition to the site setting above, you must configure a Bridge-specific setting to enable pooling for the site.

  1. While signed in to Tableau Online as a site admin, click the Bridge tab on the Settings page.

  2. Under Allow Load Balancing heading, select the Allow load balancing across Bridge clients to keep on-premises data fresh check box.

After you enable pooling for the site, as part of the publishing process, Tableau Online associates users and certain data source with Bridge and the client pool automatically.

Step 3: Add clients to the pool

By default, all Bridge 2020.2 (and later) clients are included in the pool when if the user authenticated into the client is a site admin. Follow the procedure below to add clients that were not automatically added to the pool or removed from the pool at some point.

  1. While on the Bridge tab, under Client Status, navigate to the client you want to include in the pool.

  2. In the Pool column, click the drop-down arrow and select Default.

  3. Repeat step 2 for each client you want included in the pool.

Manage pooled clients

There are a few ways you can manage your pooled Bridge clients.

Monitor data freshness tasks

You can monitor client activity using a combination of the Jobs page and built-in admin views.

Live queries

To monitor live query activity, you can use the Traffic to Bridge Connected Data Sources admin view.

Refresh jobs

To monitor refresh jobs, you can use the following resources:

  • Jobs page: The Jobs page can show you the completed, in progress, pending, canceled, and suspended refresh jobs that use Online refresh (formerly called Recommended) schedules. For more information, see About Bridge Refresh jobs.

  • Background Tasks for Non Extracts admin view: After filtering on Refresh Extracts Via Bridge, this admin view shows refresh jobs for data sources that use Online refresh (formerly called Recommended) schedules. For more information, see Background Tasks for Non Extracts.

  • Bridge Extracts admin view: This admin view shows refresh jobs for data sources that use both Online refresh (formerly called Recommended) and Bridge (legacy) schedules. For more information about this view, see Bridge Extracts.

  • Create a data source or view using client logs: Using JSON log files generated by a client, create your own data sources and views to monitor refresh jobs. For more information, see the Refresh jobs by client section below.

Refresh jobs by client

As an alternative to monitoring refresh jobs using the admin views listed above, consider creating your own data sources and views to monitor refreshes performed by a Bridge client. You can do this by using Tableau Desktop to connect to a client’s JSON log files on the machine where the client is running.

The JSON log files are comprised of objects, “k” and “v”. The “k” objects capture refresh jobs and “v” objects capture refresh details. The refreshes and their details include:

  • Refresh type (Online or Bridge (legacy))
  • Data source type and name
  • Refresh start and end time, duration, time to upload and publish
  • Errors

Step 1: Before you begin

If you want to build a view from the data of one log file, you can skip to Step 2.

If the data for a client is in multiple log files, you’ll need to union the files. You can create a script to union the log files locally or use Tableau Desktop to perform the union as described in the procedure below.


  • The procedure described below assumes you are running Tableau Desktop on the same machine as the client.
  • If you are working with multiple log files from different clients in a pool, in addition to unioning multiple logs files for a client, you can join the log files from multiple clients to monitor refreshes in a pool.
  • Connecting to JSON files directly from Tableau Online web authoring is currently not supported. For more information, see Creators: Connect to data on the web(Link opens in a new window).

Step 2: Connect to JSON logs

To build a data source and view, connect to a client’s log files using Tableau Desktop.

  1. Start Tableau Desktop and under Connect, select JSON file. Do the following:

    1. In the Select Schema Levels dialog box, select the top level schema to include “k” object details and optionally, select the "v"-level schema to include "v" object details, and then click OK.
    2. Navigate to the log file you want to connect to (for example, C:\Users\jsmith\Documents\My Tableau Bridge Repository\Logs), select it, and then click Open.
  2. (Optional) On the data source page, right-click the log files and click Convert to Union to set up a union. Do the following:

    1. Select Wildcard (automatic) tab.
    2. Next to Search In, verify the path shows the client’s Log folder.
    3. Under Matching pattern, enter ExtractRefreshMetrics_* and click OK.
  3. Select the sheet tab to start your analysis and build your view.

  4. When finished, publish the data source and view to Tableau Online separately. To ensure that your data source is kept up to date, you can set up a Bridge (legacy) refresh schedule for the data source after publishing.

Be aware that the data sources and views you create can change without warning because new log files can be generated and old log files can be deleted after certain log-specific limits are met. For more information about these limits and how to adjust them, see Change the Bridge Client Settings.

Manage registered clients

In the Client Status table, you can see a list of all the clients that are registered to the site, not just the clients that you're authenticated to. Clients can only be registered to one site at a time.

The clients you see in this list can tell you the following information:

  • Client name, which is also the name of the machine the client is installed on and running from.

  • Owner name, which in most cases is a site admin. This is the user who is authenticated (signed in) to Tableau Online from the client.

  • Pooled or not pooled:
    • Clients listed as "Default" are included in the pool. This means clients are load balancing live queries and scheduled refreshes for data sources (live connections or extract connections) that connect to on-premises relational data.

    • Clients listed as "Not pooled" are not included the pool. In most cases, clients might not be included in a pool because those specific clients have been set aside to exclusively run Bridge (legacy) schedules, which includes scheduled refreshes for data sources that connect to file data. Though clients that run Bridge (legacy) schedules can be part of client pool, the refreshes themselves cannot be load balanced.

    Note: Pools cannot be partitioned to handle live queries separately from scheduled refreshes.

  • Client version:

    • A warning icon () displays in this column when the client is not running the latest version of Bridge. Although not required, we strongly recommend upgrading to take advantage of the latest security and feature updates. To download the latest version of Bridge, go to the Tableau Bridge Releases(Link opens in a new window) page on the Tableau website.

      Note: The warning icon shows only when there is a newer client available for download. The warning icon is not an indication that there are issues with the client or related Bridge data sources.

    • Clients that are integrated with Tableau Desktop (versions 2018.1 and earlier) will not have version numbers listed.

  • Connection status—for more information see the section below.

  • Last connected—shows the day and time Tableau Online was last able to reach the client.

Client connection status

In the table of registered clients, the colored circles and status labels indicate the availability of the client to support data freshness tasks.

  • Green or "Connected": A green or Connected state indicates that the client is connected and available to support live queries (live connections) and schedule refreshes (extract connections).

  • Red or "Disconnected": A red or Disconnected state can indicate one of a few conditions that have temporarily put the client in a disconnected state. The most common scenario is if the client is not running or was unable to establish communication with Tableau Online after being launched. You can hover the mouse over the status to see a tooltip that describes the condition.


    • When the client is in a disconnected state, live queries might be disrupted. In cases like this, views that depend on data sources with live connections may properly display until the issue is resolved.
    • When a client is in a disconnected state, However, extract refreshes continue to run on schedule and manual refreshes from the client can be initiated.
  • No color or blank: Clients that are integrated with Tableau Desktop (versions 2018.1 and earlier) can't show different states of availability.

The states described above reflect and correspond to the status you see in the client.

Troubleshoot pooling

Bridge Refresh jobs fail with one of the errors listed below.

The following errors can be seen on the Jobs page and the Background Tasks for Non Extracts admin view.


    This issue can occur if there are no clients in the pool. To resolve this issue, add at least one Bridge 2020.2 (or later) client to the pool. For more information, see Step 3: Add clients to the pool.


    This issue can occur when a refresh schedule job tries to run without at least one Bridge 2020.2 (or later) client in the pool. To resolve this issue, add at least one Bridge 2020.2 (or later) client to the pool. For more information, see Step 3: Add clients to the pool.


    This issue can occur when none of the clients in the pool are available to run data freshness tasks. For more information, see the Client connection status section above.

  • "errorID=REMOTE_EXTRACT_REFRESH_ALL_AGENTS_BUSY" or "errorMessage: Maximum concurrency reached" in the client

    These issues can occur if the number of refresh schedule jobs running at a given time exceeds the capacity of your client pool. To help resolve this issue, you can do the following: 


    This issue can occur when Bridge pooling has not been enabled or turned off for the site. To help resolve this issue, enable pooling. For more information, see Step 2: Enable pooling.

Bridge clients are being signed out

This issue can happen if you deploy a large number of clients under the same Windows services account. When there are more than 10 clients running under one Windows services account, account security measures can cause clients to be logged out. For more information, see Windows services account.

Other potential pooling issues

When trying to diagnose issues related to pooling, consider reviewing the following log files for a client on the Bridge client machine: tabbridgeclijob_<process_id>, jprotocolserver_<process_id>, stdout_jprotocolserver_<process_id>. For more information, see Manage Bridge log files.

Thanks for your feedback!