Configure Java for Agent

A TeamCity build agent is a Java application (see supported Java versions).

A build agent runs two Java processes:

Agent Launcher — launches the agent process.
Agent — the main process for a build agent; runs as a child process for the agent launcher.

Using 64-bit JDK (not JRE) is recommended. JDK is required for some build runners like IntelliJ IDEA Project, Java Inspections, and Duplicates. If you do not have Java builds, you can install JRE instead of JDK.

Path to Java on Agent Machine

The .exe TeamCity agent distribution comes bundled with 64-bit Amazon Corretto 11. For the .zip agent installation, you need to install the appropriate Java version. Make it available via PATH or in one of the following places:

the <Agent home>/jre directory
the directory pointed to by the TEAMCITY_JRE, JAVA_HOME, or JRE_HOME environment variables (check that you only have one of the variables defined)
if you plan to run the agent as a Windows service, make sure to set the wrapper.java.command property in the <agent home>\launcher\conf\wrapper.conf file to a valid path to the Java executable

Upgrading Java on Agents

If you are trying to launch an agent, and it is not able to find the required Java version in any of the default locations, the agent will report an error on starting, the process will not launch, and the agent will be shown as disconnected in the TeamCity UI.

If a build agent uses a Java version earlier than Java 8, you will see the corresponding warning on the agent's page and a health item in the UI.

Information on Java versions currently supported by TeamCity Agent is available here.

To update Java on agents, do one of the following:

If an agent detects a newer Java version of the same bitness installed, the agent details page in the TeamCity UI displays the automatic update action. Click this action to restart an agent with a newer Java employed. Agents restart after they finish with their current builds and become idle.
(Windows) Since the build agent Windows installer comes bundled with the required Java, you can just manually reinstall the agent using the Windows installer (.exe) obtained from the TeamCity server Agents page. See installation instructions. It is important to uninstall the previous version of the agent before installing the updated agent: invoke Uninstall.exe in the Agent Home Directory, clear all the "Remove" checkboxes, and click Uninstall.
Install a required Java version on the agent into one of the standard locations, and restart the agent — the agent should then detect it and provide an action to use a newer Java in the UI.
Install a required Java on the agent and configure the agent to use it.

Last modified: 27 February 2023