Monitor timeouts in TeamCity

TeamCity is a Continuous Integration (CI) tool that enables software development teams to build and test their software. Sometimes the server is too busy to serve the users and the web user interface does not respond in time. TeamCity logs all actions in a log file so we can find the date and time of these timeouts:

On Windows

  1. Remote into the TeamCity server,
  2. Open the server log file at D:\TeamCity\logs\teamcity-server.log

Scroll to the bottom of the file and search for “Request processing took too long” going up to find the last timeout event.

How to upgrade TeamCity to version 10

Upgrade TeamCity to version 10

Create a backup of the database and the server before the upgrade

  1. Disable the authorized agents to stop them picking new jobs.
  2. Stop the TeamCity process on the server,
    1. If TeamCity is started by a scheduled task at startup
      1. Disable the “teamcityserver” scheduled task in the Task Scheduler,
      2. Stop the “Java(TM) Platform SE binary” process in Task Manager.
    2. If TeamCity is running as a Windows Service
      1. Stop and disable the “TeamCity” service.
  3. Save a copy of the TeamCity configuration directories to the data drive and an outside location
    1. D:\TeamCity\conf
    2. D:\ProgramData\JetBrains\TeamCity\config
  4. Create a backup image of your server,
  5. Create a backup snapshot of your database,
  6. If the image creation did not restart the serve, restart the box to make sure no processes hold files in the TeamCity install folder,
  7. Disable the Chef-Client scheduled task and Chef-Client service to make sure Chef does not alter the server during the upgrade.

Download the TeamCity installer

  1. Enable file download on your server. Set the Internet Explorer security level to Medium-high
  2. Download the TeamCity server installer
    1. To download the latest TeamCity version navigate to
    2. For earlier versions go to

Install the new version of TeamCity server

  1. Execute the downloaded installer from the Downloads folder,
  2. If the current version of TeamCity is not on the C drive, make sure you select the correct drive,
  3. It is not recommended to run agents on the server box. Uncheck the Windows Services and Core for the Build Agent,
  4. If you get Folder is not empty… messages, delete the files from the indicated locations and click the Retry button,
  5. Set the correct port TeamCity should to use 
  6. Even if you haven’t enabled the agent functionality on the TeamCity server, you will see the Configure Build Agent Properties page. Click the Save button to continue.
  7. Select the SYSTEM account to run the TeamCity service
  8. Click the Next button to start the TeamCity service


If you have specified larger memory setting than 32 bit Java is capable of handling, the TeamCity service will not start. You will get the following error message in D:\TeamCity\logs\teamcity-winservice.log

ProcessCommand [Info] Process exited with code: 1
console [Info] Error occurred during initialization of VM
console [Info] Could not reserve enough space for 2097152KB object heap
ServiceExecuteProcessTask [Error] Service process exited without service stop request

To switch to 64 bit Java, follow the steps below.

TeamCity on 64-bit Java

The TeamCity installer also installs the 32-bit version of the Java Runtime Environment (JRE) in the “D:\TeamCity\jre” folder. To use the 64 bit Java, test if your server has  64-bit Java installed:

  1. Open a command window and execute,
    java.exe -d64 -version
  2. The installed Java is 32 bit if you get the error message:
    Error: This Java instance does not support a 64-bit JVM.
    Please install the desired version.

Switch to 64-bit Java

  1. Stop the TeamCity Windows Service,
  2. Rename the D:\TeamCity\jre to OLD_jre, so TeamCity will not find it anymore,
  3. If you have not specified the memory settings in the Set the TEAMCITY_SERVER_MEM_OPTS environment variable based on the physical memory size of your server and the estimated usage
    1. Start Windows Explorer
    2. Right-click This PC and select Properties
    3. Select Advanced system settings
    4. Click the Envirnment Variables… button
    5. In the System Variables section select TEAMCITY_SERVER_MEM_OPTS
    6. Set the value based on the expected server load:
      1. minimum setting for 32-bit and 64-bit java:
      2. recommended setting for medium 64-bit server and maximum for 32-bit server:
      3. recommended setting for large server (64-bit java only):
        -Xmx4g -XX:ReservedCodeCacheSize=350m
      4. maximum settings for large-scale server use (64-bit java only):
        -Xmx10g -XX:ReservedCodeCacheSize=512m


Remove unsupported memory settings

TeamCity version 10 does not use -XX:MaxPermSize anymore. If you get

[Info] Java HotSpot(TM) Server VM warning: ignoring option MaxPermSize=2048m; support was removed in 8.0

remove “MaxPermSize” from theTEAMCITY_SERVER_MEM_OPTS environment variable.

Start the server

  1. Open Services and start the TeamCity Server Windows service
  2. Open a web browser and navigate to http://localhost:8111
  3. On the TeamCity Maintenance page select the I’m a server administrator, show me the details link
  4. Open the D:\TeamCity\logs\teamcity-server.log file and find the Administrator can login from web UI using authentication token line and copy the token number to the clipboard
  5. Paste the token to the textbox and click the Confirm button
  6. On the TeamCity Upgrade page click the Upgrade button
  7. TeamCity will make a backup of the current projects to D:\ProgramData\JetBrains\TeamCity\backup

Disaster recovery

If for some reason the server does not work after the upgrade, you can restore the database and the server from the backups you made before the upgrade.

Rebuild the environment

  1. Terminate the failed TeamCity server
  2. Restore the database from the backup snapshot
  3. Launch a new server instance from the backup server image

Make sure that the TeamCity process is not running on the restored server

When the server has started, remote into it.

  1. Check if the TeamCity process has ben stopped:
    1. If TeamCity is started by a scheduled task at startup
      1. Disable the “teamcityserver” scheduled task in the Task Scheduler,
      2. Stop the “Java(TM) Platform SE binary” process in Task Manager.
    2. If TeamCity is running as a Windows Service
      1. Stop and disable the “TeamCity” service.

Update the server configuration

TeamCity stores the address of the database and the IP address of the server in config files. To be able to use the restored server, make the following changes:

Update the database address

  1. Update the database address in the connectionUrl line of D:\ProgramData\JetBrains\TeamCity\config\

Update the IP address of the server

  1. Update the server IP address in the server rootURL element of D:\ProgramData\JetBrains\TeamCity\config\main-config.xml


  1. Restart the box for the changes to take effect.

Secure passwords in TeamCity

When a TeamCity build step needs to use a password, there is a secure way to store it.

  1. In the TeamCity web interface navigate to the project,
  2. On the project page open the Parameters page,
  3. Click the Add new parameter button,
  4. Enter the name of the parameter, the password value, and click the Edit button to set the special settings,
  5. Set the Display to Hidden, and the Type to Password to hide the value from the user interface. Click the Save button on this window and the on the parent window to save the parameter.
  6. To use the parameter in a build step, surround it with % signs.

How to rename a TeamCity agent

It is important to keep the TeamCity agent names unique. If you launch a TeamCity agent with a name that is already used by another agent that is connected to the TeamCity server, the new agent will not show up in the Unauthorized agent list.

To change the name of an agent, change the “name” value in the conf/ file.

To access the file you need to log into the box.

On a Linux agent

  • SSH into the agent,
  • Change the “name” value in the /opt/teamcity/conf/ file.

On a Windows agent

  • Remote into the agent,
  • Change the “name” value in the C:\TeamCity\conf\ file.

The location of TeamCity can be different depending on the configuration of the box.

Enable user to import projects in TeamCity

It is not enough to belong to the “System Administrator” group to be able to import projects from backup  in TeamCity. The user has to be in the “System administrator” role for the “Root project”.

To enable the user to import projects into TeamCity

  • Click the Administration link in the upper right corner
  • In the User Management section click Users
  • Click the user name in the list
  • On the Roles tab click the + Assign role button
  • Set the Role to System administrator
  • Set the Scope to Root project
  • Select the Replace existing roles with newly selected check box and click the Assign button