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:
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:
Stop Tableau Server:
tsm stop
Restart the TSM Controller:
sudo systemctl restart tabadmincontroller_0.service
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.
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 initialise.
Install fails with ‘Failed to initialise 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 initialise 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.
Initialising Tableau Server
TSM initialisation fails because the tableau
user account exists but is not a member of the group tableau
When you install and initialise Tableau Services Manager (TSM) and Tableau Server, the initialisation 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 initialising 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 initialising 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 initialisation 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 add 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 - initialising 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 full-stop ("."), initialisation 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 initialising Tableau Server after reinstallation
If you uninstall and reinstall Tableau Server, you can encounter an error initialising 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 licence 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 behaviours, 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:
Run the following command to confirm
ufw
is running:sudo ufw status
If the result is
Status: inactive
, you will need to enableufw
and ensure that you can continue to connect viassh
, which is outside the scope of these release notes.Run the following command to allow access to port 8850:
sudo ufw allow 8850
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 visualisations that display server metrics. These visualisations 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.