# Troubleshooting Known Issues

This page collects known problems that you might encounter when working with Teamscale along with their respective solutions.

# Teamscale Does Not Start: Web Interface Is Not Reachable

You are trying to start Teamscale but the web interface (usually located at http://localhost:8080) is not reachable.

Check the log files: There are several locations where logs are written that may contain helpful information about why Teamscale is not starting:

  • TEAMSCALE_INSTALL_DIR/logs
  • On Linux: TEAMSCALE_INSTALL_DIR/nohup.out
  • On Windows if you installed Teamscale as a service: TEAMSCALE_INSTALL_DIR/windows/*.log

If you are unsure which entries in the log file are related to the startup problem, you can rename the old logs, then restart Teamscale. It will automatically create new log files.

Check your JAVA_HOME setting: If you have recently updated Java, please ensure that JAVA_HOME points to the right directory. If you're running Teamscale as a service, please also check the relevant service configuration files under TEAMSCALE_INSTALL_DIR/windows and TEAMSCALE_INSTALL_DIR/linux.

Disable SSL: If you have SSL enabled, please try commenting out all options starting with https in config/teamscale.properties to temporarily disable SSL. If this works, you now know that a faulty SSL configuration is causing the startup problems.

Access Teamscale via localhost: While debugging startup problems, test Teamscale's availability by accessing it via localhost on the machine where it is installed. If this works but accessing it via the server/hostname does not, you now know that a network problem (firewall, missing connectivity) is causing Teamscale to not be available.

Run Teamscale manually: If you are running Teamscale as a service, try running it via teamscale.sh or teamscale.bat instead. If this works, you now know that there is a problem with your service setup (e.g. running as a different user with missing permissions or path misconfiguration).

# Teamscale Does Not Start: Invalid maximum heap size: -Xmx4096m

When starting Teamscale fails with an error message like Invalid maximum heap size: -Xmx4096m, this is most likely caused by using a 32-bit Java Virtual Machine (JVM). Teamscale requires a 64-bit JVM.

If Teamscale runs into memory-related problems such es OutOfMemoryError: Java heap space, please refer to the dedicated article on memory issues.

# Jira Does Not Render Teamscale Annotations Correctly

Teamscale can annotate Jira tickets with the finding/test-gap information aggregated over commits for that ticket. This can be enabled in the Jira connector in the project settings.

If it looks like in the following screenshot, Jira does not render the markdown content correctly:

Jira Integration Render Problem

This problem can be solved by configuring Jira to the wiki style renderer:

  1. Log in to JIRA as a JIRA administrator.
  2. Navigate to Administration > Issues > Field Configurations.
  3. Click on the Configure link for the field configuration used by the field to which Teamscale writes.
  4. Click on the Renders link for the field to change.
  5. Select the new renderer type from the Active Renderer drop-down list. Select the Wiki style renderer.
  6. Click on Update to apply the change.

Afterwards, Teamscale's annotations in Jira ticket should be rendered properly:

Working Jira Integration

# Cross-Site Scripting (XSS) Errors

If access to a Teamscale instance is being managed by an external server such as NGINX (which is a recommended practice), it may be necessary to adapt the header settings to accommodate the cross site scripting and request forgery guarding mechanisms built into Teamscale. Specifically, this is the case when an error message appears containing the text X-Requested-By header is missing.

To fix this, insert the following line in your NGINX configuration file at the appropriate place (e.g., the server you want to configure):

add_header 'Access-Control-Allow-Headers' 'X-Requested-By';

# Vsix-Installer Crashes When Manually Installing Teamscale's Visual Studio Extension

When installing the Teamscale Visual Studio Extension in Visual Studio 2015 on Windows 10, a XamlParseException similar to following error may occur:

System.Windows.Markup.XamlParseException was unhandled
Message: An unhandled exception of type 'System.Windows.Markup.XamlParseException' occurred in PresentationFramework.dll

As a workaround, the extension can be installed manually via the command line as follows:

\path\to\visualstudio\Common7\IDE\VSIXInstaller.exe /q <YOUR-TEAMSCALE_EXTENSION.vsix>

# TransportException: Object too large When Using Git Connector

The Git connector reports this error when a Git repository that contains a file larger than 2 GB is connected to Teamscale. This is due to internal limitations of the Java Git implementation, which unfortunately cannot be circumvented.

A possible workaround is to clone the repository with a native Git client, which doesn't have this limitation, and then exclude the problematic file from Teamscale analysis:

  1. In the workspace directory, execute git clone --bare $REPO_URL.
  2. Add the Git connector to the Teamscale project in question.
  3. When configuring the Git connector, use the Excluded file names option to exclude the respective file from analysis.

Another option is to remove the offending file from the history of the Git repository entirely, e.g., if it was added by accident. This StackOverflow question has some pointers on how to perform such an operation.

# Some URLs Do Not Work When Running As Azure App Service

Azure App Service runs your application behind a proxy server. By default, this proxy will filter certain URLs, which can lead to pages not loading correctly in Teamscale. For example, all URLs ending in .cs are blocked by default.

To resolve this, you need to adjust the web.config file in the root of your App Service similar to the following example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpplatformhandler" path="*" verb="*"
                 modules="httpPlatformHandler" resourceType="Unspecified"
                 requireAccess="Script" />
        </handlers>
        <httpPlatform stdoutLogEnabled="true" startupTimeLimit="300" startupRetryCount="0"
                      processPath="%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe"
                      arguments="%home%\site\wwwroot\HttpPlatformHandlerStartup.ps1">
        </httpPlatform>
        <security>
            <requestFiltering>
                <hiddenSegments>
                    <clear />
                </hiddenSegments>
                <fileExtensions>
                    <clear />
                </fileExtensions>
            </requestFiltering>
        </security>
    </system.webServer>
</configuration>

# Wrong Version of clang-tidy (or LLVM)

Teamscale can execute clang-tidy on your C/C++/Objective-C source code and manage the reported findings. This feature requires that clang-tidy 10.0.0 is installed on the server. We require this exact version since the checks and check descriptions supported by clang-tidy are stored in Teamscale (the clang-tidy binary has no option to print all descriptions). Our docker images already come with a clang-tidy binary. With all other distributions, you need to install clang-tidy 10.0.0 on the Teamscale server.

Automatically Check the Clang Tidy Setup

Teamscale offers a REST service to verify whether clang-tidy is correctly installed: <TEAMSCALE_URL>/api/verify-clang-tidy-setup.

# SAP Connection Does Not Import New Code Anymore

If Teamscale does not show recent code changes for one of your ABAP systems, please refer to the dedicated article on SAP connection issues.

# Teamscale JaCoCo Agent: Missing Coverage

You have attached the Teamscale JaCoCo Agent to your application according to the documentation but you are not seeing the coverage you expected or maybe even no coverage at all.

Always Check the Logs

The first step in troubleshooting such problems is always to look at the log file the agent writes at AGENT_INSTALL_DIR/logs. If it contains any errors, please resolve these first. Examples are network connectivity issues or incorrectly configured command line arguments.

It also tells you whether the agent was started at all since the agent will always log at least an INFO entry at startup.

First, we'll verify the most basic setup: The agent must at least start and write coverage files to disk. Please remove all options starting with teamscale- and the out option. This allows you to inspect the coverage reports. Coverage is written to AGENT_INSTALL_DIR/coverage. Please ensure that the agent can create files inside this directory.

Please disable all other -javaagent and -agentlib arguments to your JVM to avoid interference of other agents with the Teamscale JaCoCo agent.

Re-run your application and then shut it down. Coverage files are always written on shut down of the application.

  • A coverage file must be created in AGENT_INSTALL_DIR/coverage.
  • If not, please check the agent's logs in AGENT_INSTALL_DIR/logs.
  • If no logs were created, then the agent was not started. Please re-check your configuration and the logs of your own application.

# No Coverage Data is Generated at All

Problem: Your Application Is Not Shut Down Gracefully

If no coverage file was created or the coverage file is truncated (i.e. does not end with </report>), then it may be that your JVM did not shut down gracefully. Please ensure that no other process is forcefully killing your JVM, e.g. a service running, Docker, an application server etc.

# Coverage Files Can Be Generated But Upload to Teamscale Fails

If a coverage file was written but upload to Teamscale fails when configuring the teamscale- options, please verify that the server where the agent is installed can reach the Teamscale server.

Problem: Your Servers Cannot Reach Each Other

On the agent's server:

  • Run a ping of the IP address of the Teamscale server.
  • Run curl -v TEAMSCALE_URL/login.html and check for connection problems. Teamscale must respond with the login page's HTML, HTTP status 200.
  • Ensure that no firewalls or reverse proxies are causing issues.
  • If a proxy is required, please configure the proxy for your JVM so the agent can use it.

Problem: You Provided the Wrong Authentication Information

If a network connection is possible, common mistakes that prevent an upload to Teamscale are:

  • The teamscale-user you provided does not have the Perform External Uploads permission in Teamscale.
  • You provided the teamscale-user's password instead of their access token in the teamscale-access-token option.

# Coverage Uploads Are Shown In Teamscale But Coverage Is Missing

You can see the coverage uploads as Processed in Teamscale under Project Configuration > . You can also see the upload under Activity. However, when you click on that upload in Activity, either all or some coverage is missing when you check the list of covered files.

Problem: Your Include/Exclude Patterns Are Misconfigured

Please run the agent with patterns that include all code:

includes=*
excludes=

Run your application and upload coverage to Teamscale again If you now see the missing coverage, then your previous include/exclude patterns were not configured correctly and were excluding the code you wanted to profile.

Problem: You Are Profiling the Wrong Process

The profiler will only profile the code running within the JVM which receives the -javaagent argument. I.e. if your main Java process spawns another, it must pass on the -javaagent argument to the child process or the code running in the child will not be profiled.

Please ensure that the JVM that is running the code you wish to profile actually receives the -javaagent argument, e.g. with a process explorer tool that can show the command line of a process.

Problem: Interference by Another Java Agent

Other Java Agents can disrupt the JaCoCo agent in a way that prevents it from instrumenting your classes. Please disable all other -javaagent and -agentlib arguments to your JVM. If this resolves your issue, you have two options:

  • either leave the other agent disabled while you collect coverage
  • or try to reorder the agents so the Teamscale JaCoCo agent's -javaagent argument is the first such argument on the JVM's command line. In many cases, this will also resolve the conflict.