Troubleshoot Tableau Server on Linux


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.

The following table displays the default locations of the installation, data, logs, and scripts directories:

Directory Default location
Installation: /opt/tableau/tableau_server
Data: /var/opt/tableau/tableau_server/data
Logs: /var/opt/tableau/tableau_server/data/tabsvc/logs/
Scripts: /opt/tableau/tableau_server/packages/scripts.<version_code>/

General Troubleshooting Steps

Many Tableau Server issues can be addressed or tested with one or more of these basic steps:

Clean install

Install Tableau Server on Linux on a computer that has never had Tableau installed on it. If you are reusing a computer or VM that has had a previous version of Tableau Server installed, follow the steps in Remove Tableau Server from Your Computer to clean Tableau off your computer before you install the new version.

If you run into problems installing Tableau Server you may need to entirely remove Tableau from your computer and do a clean install. See Remove Tableau Server from Your Computer for details.

Disk space

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.

Remove old log files

If you are running out of disk space you can clean up old Tableau Server log files. These can take up space and as a best practice you should remove them regularly.

Version 10.5.x

If you have version 10.5.1 and higher, run this command at a terminal prompt to clean up log files you do not need:

tsm maintenance cleanup

Version 10.5.0

If you are running version 10.5.0 of Tableau Server on Linux, the cleanup command is not available and you need to run these commands at a terminal prompt:

sudo find /var/opt/tableau/tableau_server/data/tabsvc/temp/* -mtime +2 -type f -delete

sudo find /var/opt/tableau/tableau_server/data/tabsvc/logs/* -mtime +2 -type f -delete

Important: The Linux file system makes it possible to delete files that are open and if you do this the Tableau processes may not be able to recreate the files. This will result in empty log files. To fix this you can stop Tableau Server, restart the TSM Controller, and restart Tableau again:

  1. Stop Tableau Server:

    tsm stop

  2. Restart the TSM Controller:

    sudo systemctl restart tabadmincontroller_0.service

  3. Wait several minutes for the controller to restart. You can confirm the controller has restarted with this command:

    tsm status -v

    When you can run that command and the Tableau Server Administration Controller is listed as 'running' the controller has restarted.

  4. Start Tableau Server:

    tsm start

Manually gather logs

If you cannot run tsm maintenance ziplogs for any reason (for example, if you have a critical failure before you run tsm initialize), you can manually collect and zip the logs by running these commands in a terminal window on each node in the Tableau Server deployment:

cd /var/opt/tableau/tableau_server/data/tabsvc/

cp /var/opt/tableau/tableau_server/logs/app-install.log logs

cp ~/.tableau/tsm/tsm.log logs

tar -czvf ~/logs.tar.gz logs

This creates a file called logs.tar.gz in your home directory. You can upload or send this file to Tableau.

Restart server

Restart Tableau Server. Issues related to indexing and 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.

Edit installation and configuration files using Linux

You should edit or create any files used to install or configure Tableau Server on Linux using a Linux operating system. Files created using Microsoft Windows will cause errors in Tableau Server on Linux installation and configuration because Linux operating systems end files with a line-feed (LF) character, whereas Windows ends files with a carriage-return character and a line-feed character (CR LF). Non-Linux (CR LF) file endings can cause errors during Automated Installation of Tableau Server if they appear in the config.json, reg_templ.json or secrets files used by the automated installer. Non-Linux (CR LF) file endings can also cause errors during registration or when configuring identity store settings or gateway settings.

Check systemd logs

If Tableau Server will not start, and you do not find anything useful in the Tableau logs (see Work with Log Files for more information) you can check the systemd logs for messages related to the TSM Service starting and stopping. The logs are stored at /var/log/messages (RHEL-like distros) or/var/log/syslog(Ubuntu). We recommend using the journalctl command to search and parse the systemd logs.

Installing Tableau Server

Install fails due to hardware requirements

Tableau Server cannot install if the computer you are installing on does not meet the minimum hardware requirements. For details on requirements, see Before you install....

Install fails due to timeouts

If you install Tableau Server on a computer with limited resources, for example, a computer that just meets the minimum hardware requirements, you can run into problems where tsm commands timeout due to slow response. You can specify a longer timeout by using the global --request-timeout option on all tsm commands. For more information on the --request-timeout option, see for example, tsm initialize.

Install fails with "Failed to initialize the instance of the temporary database"

Tableau Server on Linux only supports UTF-8 character encoding. If your Linux locale is missing the UTF-8 encoding, your installation can fail with an error similar to this one:

Failed to initialize the instance of the temporary database

To check if your locale is using UTF-8 encoding, run the localectl command at a command prompt. The resulting output should look something like this (your locale may be different):

[tableauserver-centos1a ~]$ localectl
System Locale: LANG=en_US.UTF-8
[tableauserver-centos1a ~]$

If the LANG value does not include .UTF-8 then you need to run localectl to add it:

sudo localectl set-locale LANG=<your_locale>.UTF-8

Note: In some cases localectl may not complete (timeout) if your version of systemd is old. Updating systemd may fix this problem and allow you to set the UTF-8 encoding. On RHEL-like systems, use this command to update systemd: sudo yum update systemd

Installation fails on a virtual machine in Parallels

Parallels is currently not supported. If you install Tableau Server on a Linux virtual machine in Parallels, the install might fail.

Tableau Server doesn't start

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

Cannot start Tableau Server after installation

Tableau Server might not start if your computer’s hostname changes after installation. One of the main reasons why the hostname might change is if you use the cloud-init package on CentOS. If you use the cloud-init package, reboot the computer where you want to install Tableau Server before you begin the installation process. Alternatively, you can fix the hostname without rebooting by running the following command:

sudo hostnamectl set-hostname `hostnamectl --static`

The cloud-init package is commonly used to initialize new virtual machines, configure SSH public key authentication, and more. For example, some CentOS images use cloud-init, and cloud-init is commonly used in OpenStack deployments. However, the version of cloud-init included by default in the CentOS 7.x repositories (cloud-init 0.7.5-10.el7.centos.1) has a known issue that prevents your computer from displaying its Fully Qualified Domain Name (FQDN) along with its hostname until after it restarts.

Because the Tableau Server installation process uses your computer’s hostname to configure server processes and generate TLS certificates, Tableau Server might not start if it is configured to use a hostname without the FQDN.

To determine if your computer is displaying the correct hostname, run the hostnamectl command. In the following example, the command displays a transient hostname which indicates that it will not return the FQDN and must be restarted.

$ hostnamectl
   Static hostname: server01.example.com
Transient hostname: server01
[...]

Alternatively, in the following example, the command displays the correct hostname and FQDN:

$ hostnamectl
   Static hostname: server01.example.com
[...]

Cannot create initial administrator account with multiple Active Directory (AD) domains

When you create the initial administrator account on Tableau Server, you might see the following error if you selected AD as the authentication type:

Failed to authenticate username and password

This occurs when Tableau Server attempts to connect to multiple AD domains. For example, you might see this error if you install Tableau Server on a computer that is part of one domain and you attempt to authenticate AD users that are part of another domain.

Fonts

Tableau Server uses the fonts installed on the system to render workbooks based on the fonts used when a workbook was created. When a font is not available, Tableau Server will use the closest equivalent based on font families; this is true for both Windows and Linux Servers. On Linux Servers missing fonts may be more obvious because Linux ships with fewer included fonts than Windows and OS/X systems do. This matters because many workbooks are authored in Tableau Desktop on Windows or on Mac.

Tableau Server on Linux ships with the following fonts:

  • Arial
  • Courier
  • Georgia
  • Times New Roman
  • Verdana
  • Trebuchet MS
  • Tableau Font

Workbooks which use fonts other than these may appear differently than expected when viewed on Tableau Server on Linux, due to missing fonts. To resolve this issue, install the appropriate fonts onto all nodes in your Tableau Server installation.

Support for Asian character sets

If you see empty boxes where you expect to see Asian characters in workbooks that are displayed on Tableau Server, then you should install the language-appropriate font packages in your Linux environment.

Initializing Tableau Server

TSM initialization fails because the tableau user account exists but is not a member of the group tableau

When you install and initialize Tableau Services Manager (TSM) and Tableau Server, the initialization script (initialize-tsm) creates the users and groups needed to run, or confirms that the existing ones are configured with the required characteristics. By default the script creates a user called tableau and adds it to a group called tableau. If a tableau user already exists but is not part of the tableau group, the script fails with a warning.

If this happens you can fix the conflict by using a --unprivileged-user flag to specify a different user, and the user will be created and added to the tableau group.

For example, to specify a user named tableauserver, you would run the script from the /opt/tableau/tableau_server/packages/scripts.<version_code> directory using this command:

sudo ./initialize-tsm --unprivileged-user="tableauserver" --accepteula

For a complete list of options that can be used with the initialize-tsm script, use the -h option:

sudo ./initialize-tsm -h

Error initializing Tableau Server on unsupported system locale

If you attempt to install Tableau Server on a computer with a locale that is not one of the supported locales, you will get an error during installation.

Tableau Server will run on a system using one of the following locales:

de_DE, en_GB, en_US, es_ES, fr_FR, it_IT, ja_JP, ko_KR, pt_BR, zh_CN, zh_TW

fr_CA (as of version 2022.3)

th_TH, sv_SE (version 2023.1)

Any other locale will generate the error.

Error initializing Tableau Server when en_US.utf8 is not included in locale list

If you attempt to install Tableau Server on a computer that does not have en_US.utf8 in the locale list, the initialization will fail with an error. To see if en_US.utf8 is included, type locale -a at a shell prompt.

If en_US.utf8 is not listed, you can en_us to the locale list by typing sudo locale-gen en_US.UTF-8 at a shell prompt on Ubuntu, or sudo localedef -i en_US -f UTF-8 at a shell prompt on RHEL-like distributions.

Error: status 10 - initializing Tableau Server when data directory path includes a period

If you attempt to install Tableau Server and specify a data directory with a path that includes a period ("."), initialization will fail with errors including:

Connection timed out

and

ERROR: TSM services returned status 10

To avoid this issue, choose a data directory that does not include a period in its path.

Error initializing Tableau Server after reinstallation

If you uninstall and reinstall Tableau Server, you can encounter an error initializing Tableau Server. For example, you might see the following error:

ERROR com.tableau.tabadmin.webapp.asyncjobs.JobStepRunner - Running step WaitForConfigure failed
com.tableau.tabadmin.webapp.exceptions.ServiceFailedStateException

This error occurs when artifacts remain from a previous installation that cause services to fail to start. To prevent this error, use the tableau-server-obliterate script in the /opt/tableau/tableau_server/packages/scripts.<version_code> folder. For more information about completely removing Tableau Server, see Remove Tableau Server from Your Computer.

Activating Tableau Server

Tableau Server license activation fails

In certain cases activation of the Tableau product key using the tsm licenses activate -k <product_key> command fails with an error:

License Server not available

This can happen if your computer is unable to connect through TCP port 443 to the Tableau licensing server at licensing.tableau.com.

To resolve this you need to configure your network and/or host-based firewalls to allow access to that address and port, or activate Tableau offline. For more information, see Activate Tableau Server Offline.

Reindexing Tableau Server Search & Browse

Problems that can be solved by reindexing Search & Browse

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, rebuild the Search & Browse index using the tsm maintenance reindex-search command.

Restarting Tableau Server

Restarting Tableau Server or applying changes fails

If one of the Tableau Server services fails, you might see an error when you attempt to restart the server or apply configuration changes.

To see if a failed service is causing the error, type the following command:

tsm status -v

To find out why a service failed, view the tabadminagent and tabadmincontroller log files in the data directory. For example, a service might fail because of concurrency issues or port configuration issues. Please include any issues you encounter in your feedback.

As a workaround, you can attempt to resolve the failure by removing and re-adding the service in TSM. Once the service has started, you can retry your previous configuration change or retry restarting the server with the tsm restart command.

Error restarting Tableau Server after adding or configuring a node

If you add a or configure the node without a Gateway process, Tableau Server might fail to restart and you could see errors like these:

ERROR : com.tableau.tabadmin.configuration.PortConfigurationExtractor - Unable to find port config key worker1.gateway.port

and

Message: Missing port configuration value for key 'worker1.gateway.port'

These errors appear in the gateway.log file and occur when a Tableau Server node is configured with either an Application Server or VizQL Server but without a Gateway. A Gateway process is required if either Application Server or VizQL Server is running on a node.

Backup/Restore

Problems related to restoring a backup created by Tableau Server can be the result of permissions issues. Proper permissions are necessary for both the file that TSM is restoring, and the location of the file. When TSM handles the backup, it puts the file in a default location and sets permissions appropriately. You can run into permission problems if you are restoring a backup that was copied to your Linux server, or a backup from a non-default location on your server. For details about using a non-default location, including how to change the location, see tsm File Paths.

Errors may include:

Server Was Denied Access to File

or

Restoring the backup '<backup>.tsbak' was unsuccessful

or

Comparing authentication methods failed

The Tableau Server backup and restore processes must have:

  • Read permission—The processes need to access the .tsbak backup file directly.

  • Execute permission—The processes also require execute permissions to the directory structure in which the .tsbak file is placed.

When TSM creates a backup in the default location, it sets the permissions it needs. If you copy a file to the Linux server, or move it to a non-default directory, the permissions may not allow the TSM processes proper access. You need to verify that both the file, and the directory tree that contains it, allow access by the TSM user tableau. The file permissions must give the tableau user read access to the .tsbak file. You can do this by setting the group on the file to the tableau group, and giving that group read access. The directory permissions must give the tableau user read access. You can do this by setting the group on the directory to the tableau group, and giving that group read and execute access on the directories.

For detailed information about TSM and file permissions, see Files and Permissions in TSM.

File locations

Changing basefilepath does not change the location of an existing file

Several tsm commands write files to default locations. You can change these default locations for each command using a tsm set command, but doing so does not move any existing files from the original location to the new one, and it does not create the new location. You are responsible for creating the new location, and for making sure it has the correct permissions to allow tsm access to any files in the location, and the entire directory structure that contains the files.

For more information about changing default locations for backup, restore, site import and export, and ziplogs files, see tsm File Paths.

For information about tsm permissions, see Files and Permissions in TSM.

TSM commands

TSM command line does not show progress for long-running tasks

If you run a tsm command such as restore or ziplogs that takes more than 2 hours to complete, the command will continue to run until completion on the server. To display the progress of the job, use the tsm jobs reconnect command.

Opening Firewall ports

Manually opening firewall ports on Ubuntu

The current version of Tableau Server does not support the ufw firewall that is used on Ubuntu. For customers that do not want to install firewalld on Ubuntu, another option is to manually open those ports. The following steps will confirm that ufw is running, and open TCP ports 8850 and 80 to connections from any source address:

  1. Run the following command to confirm ufw is running:

    sudo ufw status

    If the result is Status: inactive, you will need to enable ufw and ensure that you can continue to connect via ssh, which is outside the scope of these release notes.

  2. Run the following command to allow access to port 8850:

    sudo ufw allow 8850

  3. Run the following command to allow access to port 80:

    sudo ufw allow 80

OpenID fails on first sign-in attempt

If you have configured Open ID Connect authentication for Tableau Server, the first sign-in attempt fails. To successfully log in, users must retry authentication after the initial failure.

Administrative views do not display

The Status tab of Tableau Server includes links to visualizations that display server metrics. These visualizations require the PostgreSQL driver to access the appropriate data from the Tableau Server repository. The PostgreSQL driver is not installed automatically, so if you have not installed the driver, the views will not display. For more information, see Database Drivers.

Note: To use administrative views, the PostgreSQL driver must be installed on any node that runs the VizQL Server process.

Changing locale on view

When you change your user locale after opening a view, any subsequent attempt to open the view will fail with an "unexpected error." You can still open views that you have not previously opened.

To work around this issue, sign out of Tableau Server after changing your locale, and then sign back in. All views will display properly.

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!