Troubleshoot Tableau Server Install and Upgrade

Follow the suggestions in this topic to resolve common issues with Tableau Server. For additional troubleshooting steps based on process status viewed on the Status page, see Troubleshoot Server Processes.

 

General Troubleshooting Steps

Many Tableau Server issues can be addressed with some basic steps:

  1. Make sure there is enough disk space on each computer running Tableau Server. Limited disk space can cause a failure to install, a failure to upgrade, or problems running Tableau Server.

  2. Restart Tableau Server. Issues related to processes not fully started can be resolved by restarting Tableau Server in a controlled way. To restart Tableau Server, use the tsm restart command. This will stop all the processes associated with Tableau Server and then restart them.

  3. Reindex Tableau Server. Issues related to indexing can be resolved by reindexing Tableau Server. To reindex Tableau Server, use the tsm maintenance reindex-search command. For more information, see Reindexing Tableau Server Search & Browse below.

  4. Restart the computer on which Tableau Server is running. Some issues, such as those related to data source connectivity, can be resolved by restarting the server computer.

Common Tableau Server Install Issues

Installation logs location

The installation logs are written to the \Temp directory of the user account that is running Setup. In most cases, this is located at C:\Users\<user>\AppData\Local\Temp.

To determine where the \Temp directory is for the logged on user, run the following command in Windows Command Prompt: ECHO %Temp%.

Install program does not prompt for location to install to

When you install Tableau Server for the first time, you will be prompted for the location you want to install to. If you do not see this prompt, you may have leftover files or directories from a previous installation, even if you uninstalled Tableau. To completely remove all traces of Tableau version 2018.2 or later, run the tableau-server-obliterate script, then restart the computer and try the install again. If the previous installation was a version earlier than 2018.2, manually delete all Tableau related folders before rerunning the install program.

Important: If you created a backup of Tableau (<file>.tsbak) you want to keep (for example, to restore to your new installation), copy that file to a safe location on another computer to guarantee it is not removed when you clean up your Tableau computer.

Install program does not restart Windows

When you install Tableau Server the Setup program may prompt you to restart Windows at the end of the installation. In certain cases, clicking Restart does not restart the computer. This can happen when a 3rd Party component installer is requesting a restart of Windows.

If clicking Restart does not restart Windows, complete the installation by manually restarting Windows.

TSM Install fails with "initialization failed" error

If you attempt to install Tableau Server and the installation fails with this error:

Tableau server initialization failed
See install log at C:\ProgramData\Tableau\Tableau Server\logs

This may be related to a permissions issue on your computer. The user is signed into Windows and installing Tableau must have administrator permissions to the C drive, to C:\Windows, and C:\Windows\System32 folders, and to the cmd.exe file. This is true even if you are not installing Tableau on the C drive.

For more information, see the Tableau Knowledge Base(Link opens in a new window).

TSM Initialize screen does not display

When installing or upgrading Tableau Server, if the browser opens but nothing displays, you may need to add the hostname to the trusted sites list. Alternatively, clear the browser cache or use a different browser. For more information, see the Tableau Knowledge Base(Link opens in a new window).

Unable to log into TSM or Tableau Server (sign in screen redisplays after entering credentials)

Using Internet Explorer or Edge, if you enter your credentials into the TSM or Tableau Server sign-in screen and the page redisplays without signing you in, verify that the hostname or domain in your URL does not include an underscore (_). If the hostname or domain of the Tableau Server computer includes an underscore (_) Internet Explorer or Edge browsers will not set a cookie, so the page will redisplay without signing you in. To work around this, use "localhost" or the IP address of the computer in the URL. For example: https://localhost:8850.

Note: If you are using AD for your Tableau Server identity store, you may be locked out of Active Directory if you try to sign in too many times.

For more information, see the Tableau Knowledge Base(Link opens in a new window).

Multiple install attempts fail

If you attempt to install Tableau Server and the install fails, any subsequent installation attempts are likely to fail unless you run the tableau-server-obliterate script to clean Tableau off the computer.

Important: You must run the tableau-server-obliterate script from a 64-bit command prompt. For example, run cmd.exe in the C:\Windows\System32 folder. If you run the script from a 32-bit command prompt, the script will not completely remove Tableau, and subsequent installations may fail. To determine if you are running a 64-bit command prompt, type echo %processor_architecture% in your command window. If the result includes "64" (AMD64 for example), the command prompt is a 64-bit prompt. If the result includes "x86" you are running a 32-bit prompt. For more information, see the appropriate Microsoft documentation for your versions of Windows.

A failed install attempt can leave the computer in a state that causes subsequent attempts to also fail with errors that don't seem directly related to a previous install attempt.

To fix this problem, run the tableau-server-obliterate script to clean up any left over remnants of the previous install attempt and then restart the computer. For more information, see Running the tableau-server-obliterate script .

Important: If you created a backup of Tableau (<file>.tsbak) you want to keep (for example, to restore to your new installation), copy that file to a safe location on another computer to guarantee it is not removed when you clean up your Tableau computer.

Obliterate script generates error: "refresh-environment-variables.cmd' is not recognized as an internal or external command

If you use Control Panel to uninstall Tableau Server and then run the tableau-server-obliterate script to completely remove Tableau from your computer, the script may generate an error about the refresh-environment-variables. This occurs because a second script called by the obliterate script was not moved to the temp directory. You can ignore this error.

Install fails due to hardware requirements

Tableau Server cannot install if the computer you are installing on does not meet the minimum hardware requirements. The requirements apply to all computers on which you are installing Tableau Server. For details on minimum hardware requirements, see Minimum Hardware Requirements and Recommendations for Tableau Server.

Common Tableau Server Upgrade Issues

Upgrade logs location

By default the upgrade log, app-upgrade.log, is written to C:\ProgramData\Tableau\Tableau Server\logs.

Upgrade multi-node, initializing additional node fails with "Enter your credentials again" error

If you attempt to initialize an additional node when upgrading Tableau Server and see this error:

Enter your credentials again. The credentials you enter must provide administrative access to the computer where you generated the configuration file.

this is an indication that the node is unable to connect to or communicate with the initial node. This can happen for multiple reasons:

  • The credentials you entered are not valid or you mistyped them. The credentials must be for a user who has administrative permissions on the computer where Tableau Server was first installed. You do not need to use the credentials of the user who created the bootstrap file but doing so will ensure you are using valid credentials.

  • The local firewall of the computer you are trying to add is not allowing communication to the initial node. For more information, see Local firewall configuration.

Upgrade stops or fails at 12%, 78%, or 92%

In certain instances, the upgrade-tsm.cmd script can stall or fail partway through. The cause of this depends on what point the script stops.

  • If the script stalls at 12% or 78% this could be due to a known issue (fixed in version 2018.2.1) related to upgrading while SSL is enabled. For more information, see the Tableau Knowledge Base(Link opens in a new window).

  • If the script stalls at 92%, while executing the "Enabling the services required for indexing" step, this can be due to problems starting Tableau Services. You can restart Tableau Server Service Manager manually to work around this issue. For details, see the Tableau Community(Link opens in a new window).

Upgrading fails due to lack of disk space

If there is not enough disk space for the Tableau Server Setup program to run and do the upgrade, the installation will fail. The amount of disk space required will depend on the size of your repository database and the number and size of your extracts.

Note: When upgrading from a pre-TSM version of Tableau Server (a version earlier than 2018.2.0), the uninstall of Tableau creates a server backup file in the data directory. This backup file has a .tsbak extension and is required for the upgrade. After you upgrade successfully, you can safely delete this file to free up space (make a copy on a computer that is not part of your Tableau Server installation in case you need the file for any reason). Do not delete this file until you have completed the upgrade and know it is working.

To free up disk space:

  1. Create a log archive snapshot using the tsm maintenance ziplogs command.

    After you create the ziplogs file, save it to a safe location that is not part of your Tableau Server installation.

  2. Clean up unnecessary files using the tsm maintenance cleanup command. For more information, see Remove Unneeded Files.

Upgrade fails on RebuildSearchIndex job

Beginning with version 2020.1.x, the final step in an upgrade is to rebuild the search index. At this point all services have been upgraded, so if this job fails, you can manually reset the search server by running the tsm maintenance reset-searchserver command. You do not need to obliterate and start over.

The error will be:

An error occurred while rebuilding search index.

To reset the search server :

  1. On the initial node, open a command prompt as administrator.

    This must be a new command prompt because the upgrade script updates system environment for the new version.

  2. Rebuild the search index using the tsm maintenance reset-searchserver command.

Import of settings file causes "not present" validation error due to missing services

If you are upgrading by installing a new version of Tableau Server and importing a settings file from an earlier version, you may encounter topology validation errors when running the tsm settings import command.

Errors will be similar to this (the specific service may be different):

                                c:\Users\mytableau\Desktop>tsm settings import -f 20183-export.json

Pending topology set.
There are 1 topology validation errors/warnings.

Service 'elasticserver' is not present on any node in the cluster.
Service: Elastic Server

To resolve this issue, add any missing services to Tableau Server:

  1. For any service that generated a validation error, add the service with an instance count of 1.

    For example, if the Messaging Service is not present in the cluster:

    Set the process instance count to 1 using the first version of the service name that shows in the validation error message:

    tsm topology set-process -n node1 -pr elasticserver -c 1

    Repeat this step for each service that results in an error.

  2. When you have no more warnings or errors, apply the pending changes:

    tsm pending-changes apply

Your settings should be imported successfully.

Import of settings file causes "configuration value you specified does not match" error

If you are installing a new version of Tableau Server and import a settings file from an earlier version, you may encounter configuration validation errors when running the tsm settings import command. These can occur when a settings file includes a configuration value that has since been removed from Tableau.

The error will look similar to this (the configuration key may be different):

                                c:\Users\mytableau\Desktop>tsm settings import -f 20183-export.json
Configuration error: At least one configuration value you specified does not match a known configuration key. This applies to the following keys: '[features.TsmConfigFileService]'
Use this parameter to override unknown key error: --force-keys

To resolve this issue, edit the settings file you are importing to remove the reference to the configuration key or keys in the error:

  1. Copy the JSON settings file and save the copy for backup.

  2. Open the JSON settings file in a plain text editor.

  3. Locate and delete the entire line that includes the key. In this example, features.TsmConfigFileService:

    "configKeys" : {
      "config.version" : 19,
      "tabadmincontroller.port" : "8850",
      "endpoints.enabled" : false,
      "endpoints.health.enabled" : true,
      "features.TsmConfigFileService" : true,
      "tableau_projects.language" : "en",

    The above is an example of a small section of an exported settings file and is not intended to represent the entire contents of the file.

  4. Save the settings file and import it again.

You may encounter additional errors related to topology validation. For information about solving those errors, see Import of settings file causes "not present" validation error due to missing services above.

Troubleshooting connections to TSM

Unable to connect to TSM

If you are able to connect to TSM from the computer where you installed Tableau (using https://localhost:8850 for example), but cannot connect from another computer (using https://<server-name>:8850), you may need to configure the local firewall on the Tableau Server computer.

Beginning with version 2018.2 you need to configure the firewall manually. For more information, see Local firewall configuration.

Starting Tableau Server

Tableau Server cannot determine if it fully started

In some instances Tableau Server may report that it could not determine if all components started properly on startup. A message displays: "Unable to determine if all components of the service started properly."

If you see this message after starting, verify that Tableau Server is running as expected by using a tsm status -v command.

If the status shows as running ("Status: RUNNING"), then the server successfully started and you can ignore the message. If the status is DEGRADED or STOPPED, see "Tableau Server doesn't start" in the next section.

Tableau Server doesn't start

If Tableau Server does not start or is running in a degraded state, run the tsm restart command from a command prompt. This will shut down any processes that are running, and restart Tableau Server.

Reindexing Tableau Server Search & Browse

Problems that can be solved by rebuilding Search & Browse index

Symptoms of an index that needs to be rebuilt include:

  • A blank list of sites when a user attempts to log in
  • A blank list of projects when a user tries to select a project
  • Missing content (workbooks, views, dashboards)
  • Unexpected or inaccurate alerts (for example, an "refresh failed" alert on a workbook that does not include an extract)

If you see any of these behaviors, reset and rebuild the Search & Browse index using the tsm maintenance reset-searchserver command.

Activating Tableau Server

Tableau Server license activation fails

In some instances Tableau Server license activation may fail. Error messages can range from a very generic one:

  • An error has occurred

To more specific messages:

  • Function flxActCommonLicSpcPopulateFromTS returned error 50030, 71521,
  • No license found for 'Tableau Server'

To resolve this issue, try these solutions in the order listed:

Confirm you can access the licensing server

The Tableau licensing service was moved to a new data center on October 6, 2018. This means any environments that required special configuration (static IP safe listing for example) to access licensing.tableau.com or licensing.tableau.com will need to be updated before you can activate, refresh, or deactivate a Tableau product key.

To test access, type the URL and the port of the licensing server in a browser:

https://licensing.tableau.com:443

and:

https://atr.licensing.tableau.com/_status/healthz

If you are able to access the server, a "Test success" message displays for the first server, and an "OK" message displays for the second.

Tableau Server needs to make a connection to the following internet locations for licensing purposes:

  • licensing.tableau.com:443

  • atr.licensing.tableau.com:443

  • s.ss2.us

  • ocsp.rootg2.amazontrust.com

  • ocsp.rootca1.amazontrust.com

  • ocsp.sca1b.amazontrust.com

  • crt.sca1b.amazontrust.com

  • crt.rootca1.amazontrust.com

  • ocsp.sca0a.amazontrust.com

  • crt.sca0a.amazontrust.com

  • ocsp.sca1a.amazontrust.com

  • crt.sca1a.amazontrust.com

  • ocsp.sca2a.amazontrust.com

  • crt.sca2a.amazontrust.com

  • ocsp.sca3a.amazontrust.com

  • crt.sca3a.amazontrust.com

  • ocsp.sca4a.amazontrust.com

  • crt.sca4a.amazontrust.com

  • crl.rootca1.amazontrust.com

  • crl.rootg2.amazontrust.com

  • crl.sca1b.amazontrust.com

Requests to the above domains may be on port 80 or 443.

Verify the date and time

Verify the date and time on the initial Tableau Server computer is correct. If the clock is set to a time and date earlier than the current date, Tableau Server cannot be activated.

Verify FlexNet Licensing Service has started

If the date and time on the Tableau Server computer are correct, verify that the FlexNet Licensing Service is running on the initial Tableau Server computer.

  1. On the initial computer, from the Windows Start menu, open services.msc.

  2. In the Services dialog box, verify that the status of FlexNet Licensing Service 64 (64-bit) or FlexNet Licensing Service (32-bit) is Started.

    If FlexNet is not listed as Started, right-click FlexNet Licensing Service and select Start.

    If the Start option is grayed out, the service may be set to Disabled. To enable the service:

    1. Right-click FlexNet Licensing Service and select Properties.

    2. From the Startup type drop-down list, select Automatic.

    3. Click the Start button, and then click OK.

Force the product key to be read again

  1. On the initial Tableau Server computer, sign in as administrator and open a command prompt.

  2. Change to the Tableau Server bin directory. By default this is:

    C:\Program Files\Tableau\Tableau Server\packages\bin.<version_code>

  3. Type the following commands:

    tsm stop
    lmreread
    tsm start

Send the contents of trusted storage to Tableau Support

If FlexNet Licensing Services is installed and running but you're still seeing an error, there might be a problem with the Tableau product key information. To resolve this issue, complete the following steps to create a file of the key information located in trusted storage.

  1. On the initial Tableau Server computer, sign in as administrator and open a command prompt.

  2. Type the following command:

    serveractutil -view > <machine_name>-LicResults.txt

    This creates the <machine_name>-LicResults.txt file in your current directory. If you don't have write permissions for that location and see an error, change to a location where you do have permission to create a file and run the command again.

  3. Contact Tableau Support (http://www.tableau.com/support/request(Link opens in a new window)) and include the <machine_name>-LicResults.txt file that you created.

tabcmd Installation Problems

Installing tabcmd separately

tabcmd is automatically installed on the initial Tableau Server node when you install Tableau Server, but if you want to run it on another computer, you need to download and install tabcmd separately. For details, see Install tabcmd.

Problems installing tabcmd on Linux

tabcmd requires Java 8 (also known as Java 1.8) to run properly. On RHEL-like systems, this will be installed as a dependency when installing tabcmd. On Debian-like systems, you need to install Java 8 (1.8) separately if it is not already installed.

Java is not installed

If you see errors similar to this when installing tabcmd, confirm that Java 8 is installed on your Linux computer:

Cannot find 'java' in your PATH. Install 'java' and make sure it is in your PATH to continue.

Incorrect version of Java is installed

If you see errors similar to these, confirm that Java 8 is installed:

Exception in thread "main" java.lang.UnsupportedClassVersionError: com/tableausoftware/tabcmd/Tabcmd : Unsupported major.minor version 52.0

or.

*** Uncaught exception NoClassDefFoundError: javax/xml/bind/JAXBException
*** See the logs for the stacktrace.
Thanks for your feedback! There was an error submitting your feedback. Please try again.