Troubleshoot Tableau Prep Builder

This article lists problems you might encounter when using Tableau Prep Builder and suggestions for how to resolve them.

When troubleshooting issues with your flow, whether debugging for yourself or contacting support, you’ll generally need to collect the log files and crash dump files for analysis, as well as document the steps needed to reproduce the error. Providing the exact steps you took before the error occurred, as well as providing the flow file, is the best way to help the developer or Support team diagnose the issue.

Collecting log and crash dump files

The Tableau prep log files are stored in the My Tableau Prep Repository folder. By default, the location is:

Windows: C:\Users\<username>\Documents\My Tableau Prep Repository\Logs.

MacOS: /users/<username>/Documents/My Tableau Prep Repository/Logs

To properly diagnose the issue, you’ll need to collect all the log files. If you are running Tableau Prep Builder, this is everything in the "My Tableau Prep Repository/Logs" folder. If you are running Tableau Prep from the command line, then include the log files from "My Tableau Prep Repository/Command Line Repository/Logs".

This table describes the different log files that are generated.

Log file name	Process that generates log file	Description
app.log	Tableau Prep.exe	User interface log file. This is produced by the JavaScript code running in the Electron process.
backendProcessManager.log	Tableau Prep.exe	This is produced by the JavaScript code that starts up and monitors the Java process.
preprestapi.log	Java.exe	This is the log file produced by the Java code. Log entries regarding rest api usage, compilation, cache management, and startup and shutdown of the tabminerva (previously prepservice) process should be here.
log.txt	prepservice.exe tabminerva.exe	This log is produced by the C++ code. This log includes all interaction with the Tableau shared technology stack including connections to databases, queries, execution, external caching, query pipeline, protocols, and more.
tdeserver.txt	tdeserver64.exe	This is the log file created by the old Tableau Data Engine. Tableau Prep still uses Tableau Data Engine.
tabprotosrv.txt	tabprotosrv.exe	The protocol server log. Anything where you use a hosted database driver will produce log lines in this file.
hyperd.log	hyperd.exe	The hyper log. Queries and errors related to queries are here.

Enable Query Logging

Starting in Tableau Prep Builder version 2026.2, you can turn on the Enable Query Logging setting under the Help > Settings and Performance menu without having to restart the application. When turned on, this setting generates an XML query file for each query that Tableau Prep Builder runs. This can be helpful when diagnosing issues with your flow. The logs are generated and stored in the Query folder.

Help menu in Tableau Prep showing Setting and Performance menu options.

You can find these query logs in the following directories:

Windows: C:\Users\<username>\Documents\My Tableau Prep Repository\Query

MacOS: /users/<username>/Documents/My Tableau Prep Repository/Query

Running LogShark

LogShark is a free open source command line utility that you can use to extract information from Prep log files to troubleshoot and gain insight about errors and usage. Using the LogShark Prep.twbx plugin, you can generate workbooks with an error and flow dashboard to help you analyze and visualize Prep issues.

For information about installing and running LogShark, see Get your Computer Set Up for LogShark.

Creating crash dump files

In addition to the log files you also want to collect crash dump files. Anything not in the log files might be detailed here and can help when troubleshooting the application startup, exceptions, or issues when querying .hyper.

When creating crash dump files, it is useful to create them for the following processes.

Process	Description
tabminerva.exe (previously prepservice.exe)	This is the native process that hosts the remainder of the Tableau Prep business logic. It is also the process that contains the shared Tableau native technology including database connectors.
hyperd.exe	This is the hyper database process. Any time a query fails. Crash dumps of hyper may be useful when a failure occurs because much of what Tableau Prep does involves queries to hyper.

To create crash dump files do the following, depending on your operating system.

Windows

Open Task Manager.
Right-click on the column header and select Process name and Command Line. This shows the different processes and enables you to select the one you want to use to create a crash dump file.
Right-click the tabminerva.exe process (previously prepservice.exe).
Select Create dump file.

A dialog will open and show the location of the crash dump file on your system.

MacOS

On MacOS, there are two types of diagnostic files useful for troubleshooting Tableau Prep:

Crash report — records the call stack at the time of the crash, similar to a stack trace.
Core file — a full snapshot of the process's memory at the time of termination.

Both require terminating the Tableau Prep process. You’ll need to relaunch Tableau Prep after collecting these files.

Prerequisite: Administrator access is required for core file collection.

Step 1: Create a crash report

Open Terminal.
Run the command: pgrep tabminerva | xargs kill -SEGV

This terminates the tabminerva.exe process by sending it a segmentation fault signal, which causes MacOS to generate a crash report automatically.
Find the saved crash report in: ~/Library/Logs/DiagnosticReports/

The file name follows the format tabminerva_YYYY-MM-DD-HHMMSS_machinename.crash or tabminerva_YYYY-MM-DD-HHMMSS_machinename.ips

When sending this file to Tableau Support or to the development team, make sure to state that you intentionally sent a segmentation fault signal to generate the report. This distinguishes it from a genuine crash.

Step 2: Create a core file

Use one of the following options to create your core file.

Create a core file and terminate the Tableau Prep session

Open Terminal.
Run the command sudo chmod 1777 /cores to grant write access to the core file directory.
Run the command ulimit -c unlimited to remove the limit on core file size for the current terminal session.
Run the command pgrep tabminerva | xargs kill -SEGV to terminate the process and generate the core file.
Find the core file in /cores/ and named core.<process_id>.

Create a core file and keep Tableau Prep running

This option uses a gcore utility to capture a core dump of a running process without ending it. This process requires the Xcode Command Line tool to be installed. To check if you have this option installed, open your Terminal and run Bash xcode-select --install.

Open Terminal.
Run the command: sudo gcore -o /tmp/tabminerva.core $(pgrep tabminerva)

This saves the core file to /tmp/tabminerva.core. Tableau Prep continues running normally.

Common errors when using the command line to run flows

You can run flows from the command line to refresh your output files instead of opening Tableau Prep Builder to run each flow manually. While this process helps build efficiency in your flow process, if your syntax is incorrect, or you are missing credentials for your connections or output locations, you will receive errors when running this process.

For a list of all command line options supported in Tableau Prep, see Tableau Prep Command Line Reference(Link opens in a new window).

The following table describes common errors and how to resolve them. For information about how to run flows from the command line, see Refresh flow output files from the command line(Link opens in a new window).

Error	Cause	How to fix it
"Missing arguments"	One of the required command line arguments is missing.	Use “tableau-prep-cli -help” to see a list of the arguments for the command line.
"Unable to read the connections file."	There are errors in the syntax or format in the credentials.json file for the input connections.	Check the syntax for the input connections in the .json file. For more information and examples, see Refresh flow output files from the command line(Link opens in a new window).
"There are errors in the flow. Unable to run the flow. Check that the credentials .json file includes all required credentials. Open the flow in Tableau Prep Builder to view error details."	There are missing credentials in the credentials.json file for the input connections or the flow has errors.	Check that the .json file has the credentials for all connections, and open the flow file in Tableau Prep Builder to see if there are any errors in the flow. If the flow has errors, you must fix them and republish the flow to Tableau Server, then try running the process again.
"Could not find match for <hostname of inputConnections >"	The credentials.json file is missing an entry for the hostname (server name).	Make sure the credentials.json file includes the correct credentials for the hostname (server name). For more information and examples, see Refresh flow output files from the command line(Link opens in a new window)
"We don't have credentials of all connections in tfl/tflx file. The following connection(s) were not found: <hostname of inputConnections>"	The credentials.json file is missing or has incorrect credentials for the hostname (server name) shown in the error message.	Make sure credentials.json file includes the correct credentials for the hostname (server name) listed in the error message. For more information and examples, see Refresh flow output files from the command line.
"Error signing in server <serverUrl> as a user <userName>. Please check the credentials."	The credentials.json file has the incorrect credentials for Tableau Server.	Make sure the credentials.json file includes all the correct credentials and elements for the output connection. For more information and examples, see Refresh flow output files from the command line
"Could not sign in successfully as <userName> to server <serverUrl>(<contentUrl>)"	The credentials.json file has the incorrect credentials for Tableau Server.	Make sure the credentials.json file includes all the correct credentials and elements for the output connection. For more information and examples, see Refresh flow output files from the command line
"We don't have credentials for Tableau Server to publish extract for one or more output nodes in tfl/tflx file."	The credentials.json file was not passed in as a command line argument or it is missing the credentials for the output connection.	Make sure the the path to the credentials.json file is included in the command line and verify that the credentials.json file includes all the correct credentials and elements for the output connection. For more information and examples, see Refresh flow output files from the command line
"Loom rest api server not started"	The installation or environment setup is incorrect.	Make sure that Tableau Prep Builder is installed correctly and that you are running the command as an Administrator. For information about how to install Tableau Prep Builder, see Install Tableau Desktop or Tableau Prep Builder from the User Interface(Link opens in a new window).
"Error. Flow file does not exist."	The path to the flow file is incorrect.	Make sure that the correct path to the flow file is included in the command line.
"Error. Connections file does not exist."	The path to the credentials.json file is incorrect.	Make sure that the correct path to the credentials.json file is included in the command line.
"Could not find match for <mapr01:5181>,<mapr02:5181>,<mapr03:5181>"	You must specify a specific Port ID when connecting to Apache Drill using ZooKeeper .	Include a credentials.json file in the command line that specifies "port": 31010 for the input credentials.

Common Tableau Prep errors

The following table describes some common errors you might encounter when using Tableau Prep along with solutions to try.

Error	Cause	How to fix it	Knowledge article
Can't connect to Tableau Server. Check that the server is running and that the URL is correct. `tableauErrorCode=0xD5A9A6F9; tableauStatusCode=UNAUTHENTICATED; exceptionName=VizportalAuthenticationException`	A proxy or firewall is blocking Tableau Prep Builder's embedded browser from completing the Tableau Cloud login handshake.	Work with IT to safelist Tableau Cloud URLs through the proxy. Sign out and back in from within Tableau Prep Builder. If an automatic proxy configuration script is in place, verify it handles authentication without prompting for credentials.	Unable to sign in to Tableau Online from Tableau Prep Builder in an authentication-required Proxy environment(Link opens in a new window)
The required SSL certificate might be missing or doesn't match the Tableau Server certificate for [serverhostname]. Also seen as "Unable to find requested certificate path for flow ID" when running flows on the server.	Missing SSL certificate chain file on Tableau Server, or the chain file is not installed on the machine running Tableau Prep Builder. In some cases, the issue is caused by an AWS load balancer using an incompatible TLS policy.	Ensure the SSL certificate chain file is uploaded to Tableau Server. Install the certificate on the machine running Prep Builder (if double-clicking and selecting "Install Certificate" returns "The file is invalid for use as the following: Security Certificate", the cert file itself may be malformed. Work with IT to export a valid chain file. If behind an AWS load balancer, downgrade the policy to ELBSecurityPolicy-TLS-1-2-2017-01.	Error - The required SSL certificate might be missing or doesn't match the Tableau Server certificate - signing in from Tableau Prep(Link opens in a new window)
Tableau Prep Builder stopped running because an underlying process stopped unexpectedly. If the problem continues, try reinstalling the product.	This can be triggered by multiple factors: VPN/network configuration (confirmed with Cato Network VPN blocking localhost communication), anti-virus interference, or a corrupt port file when opening a specific .tfl file. Note: Tableau Prep Builder should never be installed on a Tableau Server node. This is a known cause of this error.	Reinstall, check AV exclusions, verify localhost IPv4/IPv6 communication If VPN-specific, test with an alternate VPN to isolate; engage network team to check for localhost blocks If tied to a specific .tfl file, collect Prep logs and IPS dumps to investigate tabminerva process crashes Ensure Tableau Prep Builder is not installed on any Tableau Server node.	Error: Tableau Prep stopped running because an underlying process stopped unexpectedly when starting Tableau Prep(Link opens in a new window)
AqlProcessor evaluation failed: Canceled" — flow fails after a pivot step	Known issue when changing the value of a pivoted column after the pivot step.	Note: This fix applies to versions 2022.2 and later. Upgrade to a version covered by the fix. As a workaround on older versions, avoid modifying pivoted column values in steps downstream of the pivot.	Error: System error - An error occurred while communicating with data source (LoomDataSource) occurs when changing the value of a pivoted column after the pivot step(Link opens in a new window)
This flow requires more memory than is currently allocated to perform this action. Consider filtering your data or breaking the flow into smaller parts.	The size or complexity of the flow requires more memory than is available to complete the flow job in Tableau Cloud.	Simplify the flow. Try removing unused fields, applying filters, moving filters or aggregations before a join to shrink the table. Try splitting the flow into smaller flows, using the flow outputs as an input for a final flow. For more ideas see Best Practices to Improve the Performance of Your Data Preparation Flows(Link opens in a new window).	Error "Cannot allocate ###### bytes of memory: The `global memory limit` limit of ###### bytes was exceeded" When Attempting to Run a Flow(Link opens in a new window)
Unable to publish the data source" — flow runs successfully locally or when outputting to a .hyper file, but fails when publishing to Tableau Cloud.	Flow fails due to the size of the temp file exceeding Tableau Cloud limits. Also seen when a flow fails with memory-related SQL errors (e.g., large JOIN operations) that only surface in Tableau Cloud, not locally.	Switch output to a local .hyper file to confirm the issue is Cloud-specific. Reduce flow complexity, break into smaller flows, remove unused columns, or use live connections.	N/A
Prep Builder fails to open on Windows; debug logs show an error related to a relative temp folder path.	The Windows TEMP environment variable is set to a relative path (e.g., `%USERPROFILE%\AppData\Local\Temp`) or contains a duplicate path entry. Tableau Prep Builder requires an absolute path.	Verify the Windows TEMP environment variable is set to an absolute path (e.g., `C:\Users[username]\AppData\Local\Temp`) Remove any duplicate entries from the TEMP variable.	N/A

Tableau Prep Help