Troubleshoot

Logging

MailScheduler keeps track of errors in log files. These log files can be viewed in the application and are also visible in the file storage on the machine.

• In the frontend, Click on About in the menu and click the pink System logs button. At the left there is a list of log files. The left part of the page shows the lines in the log files. Clicking on a line will open the details of the log item. There is also a download logs button that will compress all log files into a zip file for easy sending.
• On the filesystem in the directory where MailScheduler.exe is located, there is a directory .app-runtime/storage/logs which contains all log files.

When you encounter an error in the application, it is always helpful to send the logs with the support ticket so we can directly start investigating.

Application startup

When the application does not start, the cause can probably be found in the log files. they are located in <installation_path>/.app-runtime/storage/logs/*.log. When opening a support ticket, please provide these files.

Could not startup server, Contact Apps For Tableau support when the problem persists

The app server is unable to start. This can have multiple causes like:

• Application is configured as administrator but is currently not running with administrator privileges.
• Check if there is no other MailScheduler process running in the background. Open Task manager and select the Details tab. You should have only one process called MailScheduler.
• Check if there is no other process running on the port that is configured in MailScheduler. You can do that with this command in cmd:

netstat -aon

• Open power shell and navigate to the directory where MailScheduler.exe is located. run this command to manually trigger the application server:

./MailScheduler.exe serve

This command might give more details about what went wrong.

listen tcp :443: bind: Only one usage of each socket address (protocol/network address/port) is hormally permitted

When this error appears in your go-application.log it is not able to spin the server because the port you have configured is already in use by another program.

MailScheduler is slow or unresponsive

A typical reason of a slow experience is the connection to tableau. MailScheduler uses the REST API to fetch the visuals from Tableau. Each unique combination of filters will cause an extra request to tableau for fetching this information. On large mailing lists this can cause delay.

When the frontend for example is slow you can take a look at the application performance. Open Powershell and navigate to the directory where MailScheduler.exe is located. Run this command to see the statistics of the internal workers:

./MailScheduler.exe workers --interactive

This will generate an interactive statistics table like so:

Allowed memory size of xxx bytes exhausted

Big tasks can involve large amounts of memory. This error indicates that MailScheduler is trying to use more memory than the memory limit is allowing. To resolve this issue, increase the memory limit by altering the memory limit setting in the One-Click Advanced settings

A generally 'safe' memory limit is 1G, which stands for 1 Gigabyte.

After setting the new limit, make sure you press the 'Submit' button to apply it.

SMTP / Mail Server (TLS & Encryption Issues)

Use this section if you encounter SMTP connection errors such as TLS version mismatch, “wrong version number”, or failures when sending emails from MailScheduler.

Recommended SMTP Port & Encryption combinations

If you encounter TLS or SSL errors, the issue is often caused by an incorrect port and encryption configuration.

Port	Encryption	Connection behavior
25	None / Plain	Plain → STARTTLS
25	STARTTLS	Plain → STARTTLS
587	STARTTLS	Plain → STARTTLS
465	SSL (SMTPS)	SSL/TLS from start (implicit TLS)

⚠️ If you see a TLS version mismatch error, the port is very likely configured with the wrong encryption type.

Common Causes of TLS Errors

• Incorrect encryption selected for the chosen port
• Port 465 configured as SMTPS but encryption set to STARTTLS
• Port 587 or 25 configured without STARTTLS
• Firewall blocking the SMTP port
• Mail server only supporting TLS 1.2 while the client attempts TLS 1.3

Check if SMTP ports are reachable (Windows / PowerShell)

Run the following commands from the machine where MailScheduler is installed:

Test-NetConnection smtp.example.com -Port 587
Test-NetConnection smtp.example.com -Port 465

If the connection fails, the port may be blocked by a firewall or network rule.

Determine How Port 465 Is Configured (Linux / macOS / WSL)

Port 465 can be configured in two different ways depending on the mail server. Use the commands below to determine which one applies.

SMTPS (Implicit TLS)

Use this if the server expects SSL/TLS immediately on connection:

openssl s_client -connect smtp.example.com:465 -servername smtp.example.com

SMTP + STARTTLS on Port 465

Use this if the server starts in plain text and upgrades to TLS:

openssl s_client -starttls smtp -connect smtp.example.com:465 -servername smtp.example.com -crlf

If one command succeeds and the other fails, configure the mail server settings accordingly.

Inspect the Raw SMTP Response (Advanced – PowerShell)

If neither OpenSSL command succeeds, you can inspect the server’s raw response before the connection is dropped using PowerShell:

(New-Object IO.StreamReader (
  (New-Object Net.Sockets.TcpClient("smtp.example.com",465)).GetStream()
)).ReadLine()

This can help identify whether the server is responding with SMTP, SMTPS, or an unexpected protocol.

Summary

If you encounter TLS or SSL errors:

1. Verify the port and encryption combination
2. Confirm the port is reachable from the application server
3. Test whether the server expects implicit TLS or STARTTLS
4. Adjust the configuration accordingly

Most “TLS version mismatch” errors are resolved by correcting the port + encryption settings.

MailScheduler Requires Service Restart After Credential or PAT Updates

Symptom

Scheduled reports in MailScheduler continue failing with Tableau authentication errors even after updating the Tableau PAT or SMTP credentials. Users may see errors such as:

• 401001 Authentication failed
• 535 Authentication unsuccessful

SMTP or credential validation in the UI may still succeed while scheduled jobs continue failing.

Cause

MailScheduler background workers/queue processes can continue using stale cached credentials after credential or PAT updates are made in the application.

As a result, scheduled jobs may continue attempting authentication with outdated credentials until the MailScheduler service is restarted.

Resolution

Restart the MailScheduler service/application after updating Tableau PATs or authentication credentials.

This refreshes the active workers/processes and forces MailScheduler to load the updated credentials.

Single Sign-On

Common error messages:

A valid SubjectConfirmation was not found on this Response

This could indicate there is a mismatch between the Recipient and Destination URLs. Check in the SAML response XML if Recipient and Destination URL's match. When it does not match it should be configured in your SAML provider.

Unknown AssertionConsumerServiceURL

The URL in the configuration file is probaby incorrect. Check your config.toml file and look at the app.url variable. That should match the domain that is used to access MailScheduler

Authentication method by which the user authenticated with the service doesn't match requested authentication method

This problem occures/happends, because of the way how the session authentication method (SAML AuthnRequest) is configured on the other SSO app. MailScheduler by defaults use “Password, ProtectedTransport” as request authentication method.

Solution

We have added a configuration variable to allow all options, but allow any cross request authentication method. Within the config.toml file, set the following variable to not strictly check on the cross request authentication method:

[env.portal.saml]
requested_auth = false

Performance

Starting with version 5.1, MailScheduler provides much more detailed performance information for schedules and their underlying jobs. Each important step within a job is now measured individually, making it easier to identify bottlenecks and analyze execution times.

5 concurrent connections, where the 6th starts when the first request ends

In most environments, the primary causes of slower job execution are downloading Tableau views and merging CSV or PDF files. Download performance is heavily influenced by the Tableau Server itself. Based on our observations, Tableau Cloud environments are generally less affected and show more consistent performance over time.

The example below illustrates a case where the performance of Tableau view downloads gradually degrades during the day. The blue and orange trend lines show increasing execution times, while the red and green lines remain relatively stable.

To validate whether download performance is impacting your jobs, review the Tableau Server Apache2 logs and look for requests ending in /pdf or /csv. These requests can help identify server-side delays and confirm whether Tableau Server is the source of the performance degradation.