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:

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.
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.
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.
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 install log, app-install.log, is located in /var/opt/tableau/tableau_server/logs.

The upgrade log, app-upgrade.log, is located in /var/opt/tableau/tableau_server/logs.

Multiple install attempts fail

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

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. One possible error is:

Enabling and starting all services
+ services=(appzookeeper* tabadmincontroller* tabsvc* licenseservice* fnplicenseservice* tabadminagent* clientfileservice*)
+ systemctl_user enable appzookeeper_0.service 'tabadmincontroller*' 'tabsvc*' 'licenseservice*' fnplicenseservice_0.service 'tabadminagent*' 'clientfileservice*'
++ id -ru a_tabadminpoc
+ local unprivileged_uid=222954
+ su -l a_tabadminpoc -c 'XDG_RUNTIME_DIR=/run/user/222954 systemctl --user enable appzookeeper_0.service tabadmincontroller* tabsvc* licenseservice* fnplicenseservice_0.service tabadminagent* clientfileservice*'
Failed to execute operation: No such file or directory

To fix this problem, run the tableau-server-obliterate script to clean up any left-over remnants of the previous installation 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.

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.

Install or upgrade fails due to CPU requirements

Beginning in version 2020.4.0 Tableau Server requires CPUs that support SSE4.2 and POPCNT instruction sets. You cannot install or upgrade Tableau Server 2020.4.0 or oater on computers that have CPUs which do not support these instruction sets.

You may see this error message when installing a new installation, or in preparation for upgrading an existing installation:

Your computer’s processor doesn’t meet the minimum requirements that Tableau requires to install the software. If you are using a VM, make sure Processor compatibility mode is off.

The SSE4.2 and POPCNT instruction sets have been common for more than 10 years and most newer CPUs support them, but if you get an error related to processor minimum requirements when attempting to install or upgrade Tableau Server on a Virtual Machine (VM), Processor compatibility mode may be enabled on the VM. To successfully install or upgrade Tableau on a VM, make sure the Processor compatibility mode is turned off.

Common Tableau Server Upgrade Issues

Upgrade logs location

The upgrade log, app-upgrade.log, is located in /var/opt/tableau/tableau_server/logs .

Maps do not display or display incompletely after upgrading

Beginning with Tableau version 2019.2, the internet access requirements changed for maps. If you are upgrading from version 2019.1.x or earlier to version 2019.2.x or later, and maps are not displaying as expected, confirm that your environment is configured to allow access on port 443 to mapsconfig.tableau.com and api.mapbox.com.

In version 2019.1.x or earlier, access was necessary to maps.tableausoftware.com.

For more details on internet access requirements, see Communicating with the Internet.

Upgrade script error: "Tableau Server Version change validation failed."

When upgrading, if you run the upgrade-tsm script from the scripts.<version_code> directory for the earlier version, the upgrade will fail with an error:

Tableau Server Version change validation failed.
Tableau Server <version> is already installed.

If you get this error, change to the scripts.<version_code> directory for the version you just installed and run the script from there.

Upgrade multi-node, initialising additional node fails with ‘Enter your credentials again’ error

If you attempt to initialise 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.

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.

To free up disk space:

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.
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 :

On the initial node, open a terminal session.
This must be a new terminal session because the upgrade script updates the system environment for the new version.
Rebuild the search index using the tsm maintenance reset-searchserver command.

Upgrade fails on 2022.1 and later

After upgrading Tableau Server 2022.1 (or later), restoring a Tableau Server backup as part of your upgrade process can cause the following error:

“The backup cannot be restored because Tableau Server uses the new identity service tables by default.”

This issue occurs because Tableau Server 2022.1 (and later) uses an identity schema that is different from the identity schema used by the backup. To resolve this issue, see Troubleshoot Issues with the Identity Migration.

Upgrade fails on 2020.4.0 or later

Beginning with version 2020.4.0, the Checkpoint Upgrade feature allows you to retry a failed upgrade. In general, this is most useful for experienced server administrators and IT professionals who are comfortable with Tableau Server log files and are willing to search through them. But the feature can help in all failed upgrades because it allows you to rerun the upgrade-tsm script, and the script is run from the last successful step, saving time. For those with experience, it may be possible to identify problems like disk space problems or permissions issues, correct them, and rerun the upgrade.

If you are upgrading to version 2020.4.0 or later and the upgrade fails, the following steps may help you to complete the upgrade:

Rerun the upgrade-tsm script. Upgrade failures are sometimes a result of timeouts during the upgrade process, and rerunning the script can allow the upgrade to get beyond intermittent or occasional timing issues. This is also a step that is safe and easy to do. Rerunning the script will do no harm, and at worst, the upgrade will fail again at the same point, but without needing to go through any previous steps.
The script is located in the \scripts directory:
opt/tableau/tableau_server/packages/scripts.<version_code>/upgrade-tsm
If your Tableau Server upgrade isn't successful when you rerun the upgrade-tsm script, and you are comfortable with Tableau Server logs, you can take these additional troubleshooting steps:
Look at the output of the script in the command window. Useful error messages may help you identify the cause of the upgrade failure and give you some ideas for how to correct the issue.
Look in the app-upgrade.log file. Any errors that are displayed at the command line will also appear in the app-upgrade.log file, often with more details.
Look in the tabadmincontroller.log file. Upgrade problems that aren't easily identifiable in the above two instances are likely the result of an issue in a job. The tabadmincontroller.log file may have more information that helps you diagnose the issue.
Note: For information about log file locations, see Tableau Server Logs and Log File Locations.

Upgrade fails due to permission problems with the backup/restore file location

With versions of Tableau Server before 2022.1.0, if the file location for the backup/restore file does not have the correct permissions, the upgrade script will fail with an error about not being able to read the backup file or not being able to restore the repository.

Beginning with version 2022.1, the upgrade script confirms the permissions of file location for the backup/restore file before starting the upgrade so the file can be written to and read from the location during the upgrade to the new version of Tableau Server.

The errors will be similar to these:

The tableau user does not have permission to read the backup file: <backup/restore basefilepath>.

Repository restore failed.
An error occurred during installation.
An error occurred while restoring repository.

The location used by TSM for backup and restore is defined by the basefilepath.backuprestore configuration key and has a default that the installation program sets up with correct permissions, but these may be impacted by organisation IT rules or if you change the location to one you have created yourself. A new command available starting in 2022.1 allows you to check the permissions on the backup/restore file location immediately after creating it to avoid any permission-related problems. For details about that command, see tsm maintenance validate-backup-basefilepath.

For details about the backup/restore file path, see tsm File Paths.

Upgrade succeeds but published data sources cannot be accessed

In limited, specific scenarios, after upgrading Tableau Server from version 2021.3 to early versions of 2023.1 or 2023.3, attempts to connect to or refresh existing published data sources fail with this error:

java.io.FileNotFoundException: Unable to fetch data from any other host. This may indicate a lost or invalid folder.

This could happen if:

You upgrade a Tableau Server installation that was version 2021.3.x at any point (you could be running 2021.3 or have upgraded from 2021.3 to a 2022.x version)

and
You upgrade that installation to early versions of 2023.1 or 2023.3

No impact

There are no problems in the following situations:

In all other upgrade paths from 2021.3
In all other upgrade paths to 2023.1 or 2023.3
In all fresh installations of 2023.1 and 2023.3

More information

As of 16 September 2024, all problematic versions have been removed from the download site. If you need to upgrade to version 2023.1.x or 2023.3.x, upgrade to maintenance release versions 2023.1.16 or higher, or 2023.3.9 or higher.

For more information about this issue, see the Known Issue(Link opens in a new window).

Common Settings Import Issues

Import of settings file causes "not present on any node" 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.

This can happen when you export a settings file from an older version of Tableau Server and import it into a new version, and new services have been added to Tableau between the two versions.

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

>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:

For any service that generated a validation error, add the service with an instance count of 1.
For example, if the Elastic Server is not present in the cluster, set the process instance count to 1 using the service name that appears in the first line of 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.
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):

>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:

Copy the JSON settings file and save the copy for backup.
Open the JSON settings file in a plain text editor.
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.
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 on any node" validation error due to missing services above.

"You cannot directly modify instances of the Coordination Service" error

This error can occur in two situations:

When you import a Tableau Server settings file into an installation that has a different Coordination Service topology than the settings file does
When you attempt to configure the Coordination Service using the tsm topology set-process command

If you see this error after importing a settings file:

The Tableau Server settings file has a different Coordination Service topology than the target server does. This can happen if you are upgrading Tableau Server by installing a new version and importing a settings file from an earlier version. If you have not explicitly deployed a Coordination Service ensemble on the target server, it has a single instance of Coordination Service, on the initial node.

To correct this error you can take either correct the mismatch from the command line, or by editing the settings import file. You can also discard all pending changes, deploy the Coordination Service on the target computer to match the settings in the import file, and reimport the settings file.

To correct the mismatch from the command line, for each node that generates an error, use the tsm topology set-process command to revert the instance count of Coordination Service.

Run the tsm pending-changes list command. The output shows you which nodes have changes.
Find the node or nodes where the Coordination Service count is changed.
For example, if the settings file had a Coordination Service instance on node2, but the target system did not have any Coordination Service instance on that node, the count for node 2 would show as changed from 0 to 1 by the import of the settings file:
```
C:\Windows\system32>tsm pending-changes list
Configuration
There are no pending configuration changes.
Topology
node2:
            Coordination Service
                                New Instance Count:1 
                                Old Instance Count:0
```
Use the tsm topology set-process command to set the count back to the "Old Instance" value.
For the example above:
```
tsm topology set-process -n node2 -c 0 -pr "Coordination Service"
```
Once you have reset any Coordination Service instance count that was changed, apply pending changes:
```
tsm pending-changes apply
```

If you see the error when setting the process count for Coordination Service manually:

This error can also occur if you attempt to update the Coordination Service directly, using the tsm topology set-process command instead of the tsm topology commands for managing the Coordination Service. If you tried this:

Use the tsm pending-changes discard command to discard the pending changes.
Use the correct commands for configuring the Coordination Service. For more information, see Deploy a Coordination Service Ensemble.

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 behaviours, reset and rebuild the Search & Browse index using the tsm maintenance reset-searchserver command.

Activating Tableau Server

Tableau Server licence activation fails

In some instances Tableau Server licence 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 centre on 6 October 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:

atr.licensing.tableau.com:443
licensing.tableau.com:443
register.tableau.com:443
o.ss2.us
s.ss2.us
crt.rootca1.amazontrust.com
crt.sca1b.amazontrust.com
crt.sca0a.amazontrust.com
crt.sca1a.amazontrust.com
crt.sca2a.amazontrust.com
crt.sca3a.amazontrust.com
crt.sca4a.amazontrust.com
*.digicert.com
ocsp.*.amazontrust.com
crl.*.amazontrust.com
crt.rootg2.amazontrust.com

Requests to the above domains may be on port 80 or 443. Port 80 is used for certificate validation (revocation, certificate chain, etc). Port 443 is used for SSL connections.

Requests to the ocsp.*.amazontrust.com and crl.*.amazontrust.com domains are managed by Amazon for certificate revocation information. See ACM certificate characteristics(Link opens in a new window) for more information. We recommend that you install the Amazon root certificates in the certificate trust store on the computer running Tableau. To download and install the Amazon root certificates, see Certificate Authorities(Link opens in a new window) on the Amazon Trust Services website.

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.

Force the product key to be read again

On the initial Tableau Server computer, log on as a user with sudo access.
Change to the Tableau Server bin directory. By default, this is:

/opt/tableau/tableau_server/packages/bin.<version_code>/
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.

On the initial Tableau Server computer, log on as a user with sudo access.
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.
Contact Tableau Support (http://www.tableau.com/en-gb/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 11 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 11 separately if it is not already installed.

As of July 2022, Debian distributions are no longer supported. For more information, see this Tableau Community post(Link opens in a new window).

Java is not installed

If you see errors similar to this when installing tabcmd, confirm that Java 11 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 11 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.

Tableau Server on Linux Help