TeamCity On-Premises 2021.1 Help

TeamCity Maintenance Mode

If you see the TeamCity Maintenance page on the TeamCity startup, it means this TeamCity instance requires technical maintenance before it can start. In most cases, this page appears if the data format expected by the TeamCity installation does not correspond to the data format in the Data Directory or the database; for example, during upgrade TeamCity will display this page before converting the data to a newer format.

For security reasons, it is to be performed by a system administrator who has administrative access to the environment where the TeamCity server is installed. If you do not have access to the computer where TeamCity is installed, inform your system administrator that TeamCity requires technical maintenance.

If you are a TeamCity system administrator, confirm it by entering the authentication token into the corresponding field on this page. This token can be found in the teamcity-server.log file under <TeamCity home>/logs.

After you have provided this token, you can review the details on what kind of maintenance is required. The need in technical maintenance may be caused by one of the following factors:

TeamCity Data Upgrade

When updating your TeamCity instance to a new feature release, the newly installed version of TeamCity checks if the TeamCity Data Directory and database use the same data format as required by the TeamCity version. If the newer version requires data conversion, this page is displayed with data format details. Review them carefully to ensure that the Data Directory and the database locations are indeed those meant to be used by the server.

If you haven't backed up your data before, do it at this point by using the option on the page. Note that the backup process can take time, especially with large TeamCity installations. Other ways to create the backup are detailed in the TeamCity Data Backup page.

Once TeamCity converts the data, downgrade will not be possible. If you need to return to an earlier TeamCity version, you will be able to do that only by restoring the data from a corresponding backup.

When you are sure you have backed up your data, click Upgrade.

New TeamCity Data Format

TeamCity has detected that the data format corresponds to more recent TeamCity version than you try to run. Since downgrade is not supported, TeamCity cannot start until you provide the data that matches the format of the TeamCity version you want to run. To do so, restore the required data from backup. Refer to the Restoring TeamCity Data from Backup page for the instructions.

TeamCity Startup Error

If a critical error was encountered on TeamCity startup, this page will display the error message. It is required to fix the error cause and restart the TeamCity server.

TeamCity Database Creation

If you see this screen when setting up TeamCity with an external database or after migrating to an external database, click Proceed to create a new database for TeamCity.

Last modified: 28 September 2021