Create a new database with the appropriate character set and collation. We recommend using a unicode case-sensitive collation: see instructions for PostgreSQL and MySQL. For MySQL,
Copy the current
TeamCity Data Directory
>/config/database.propertiesfile, and change the database references in the copy to the newly created database.
- Stop the TeamCity server.
maintainDBtool to migrate to the new database:
maintainDB migrate [-A <path-to-data-dir>] -T <new-database-properties-file>
Depending on the size of your database, the migration may take from several minutes to several hours. For more information on the
maintainDB tool, see this section.
- Upon the successful completion of the database migration, the
maintainDBtool should update the
TeamCity Data Directory
>/config/database.propertiesfile with references to the new database. Ensure that the file has been updated. Edit the file manually if the tool fails to do it automatically.
- Start the TeamCity server.
MySQL exception: Specified key was too long; max key length is 767 bytes
Index column size too large. The maximum column size is 767 bytes
Check if the charater set of your MySQL database. It is recommended to use the
utf8 character set.
If your database uses the
utf8mb4 character set (available since MySQL 5.5), set the the following InnoDB configuration options (under
[mysqld] section in
my.ini) for TeamCity 2017.2.1+ to run:
innodb_large_prefix=1for index key prefixes longer than 767 bytes (up to 3072 bytes) to be allowed for InnoDB tables that use DYNAMIC row format (deprecated in MySQL 5.7.7).
innodb_file_format=Barracudato enable the DYNAMIC row format.
innodb_file_per_table=1to enable the Barracuda file format
The parameters above have the following default values:
|MySQL 5.5.59||MySQL 5.6.39||MySQL 5.7.21||MariaDB 5.5.58||MariaDB 10.0.33||MariaDB 10.1.30||MariaDB 10.2.12|
Depending on the database server version, the following configuration changes need to be made:
MySQL 5.6 and MariaDB from 5.5 to 10.1:
For MySQL 5.7+ and MariaDB 10.2+ use the defaults, no changes are required.
'This driver is not configured for integrated authentication' error with MS SQL database
To solve the problem, do the following:
- Make sure you use the MS SQL native driver (downloadable from the Microsoft Download Center).
- Use the right JRE bitness — ensure that you are running TeamCity using Java with the same bitness as your
sqljdbc_auth.dllMS SQL shared library.
By default, TeamCity uses the 32-bit Java. However, both 32-bit and 64-bit Java versions can be used.
To run TeamCity with the required JRE, do one of the following:
- either set the TEAMCITY_JRE environment variable
or remove the JRE bundled with TeamCity from
<TeamCity home>\jre and set JAVA_HOME.
Note that on upgrade, TeamCity will overwrite the existing JRE with the default 32-bit version, so you'll have to update to the 64-bit JRE again after upgrade.
See also this related external posting.
Protocol violation error (Oracle only)
This error can occur when the Oracle JDBC driver is not compatible with the Oracle server. For example, Oracle JDBC driver version 11.1 is not compatible with Oracle server version 10.2.
In order to resolve the problem, use the Oracle JDBC driver from your Oracle server installation, or download the driver of the same version as the Oracle server.
Common Maven issues
There are two kinds of Maven-related issues commonly seen in the TeamCity build configurations:
- Error message on "Maven" tab of build configuration: "An error occurred during collecting Maven project information ... "
- Error message in build configuration with Maven dependencies trigger activated: "Unable to check for Maven dependency Update ..."
If the build configuration produces successful builds despite displaying such error messages, these errors are likely to be caused by the server-side Maven misconfiguration.
To collect information for the Maven tab, or to perform Maven dependencies check (for the trigger), TeamCity runs the embedded Maven. The execution is performed on the server machine, and any agent-side maven settings are not accessible. TeamCity resolves the
settings.xml files on the server-side separately, as described on this documentation page.
It makes sense to check if the
server-side settings.xml files contain correct information about remote repositories, proxies, mirrors, profiles, credentials etc.
"Critical error in configuration file" errors
If you encounter the error, it means the settings stored in the TeamCity Data Directory are in inconsistent state. This can occur after manual change of the files or if newer version of TeamCity starts to report the inconsistencies.
To resolve the issue, you can edit the file noted in the message on the server file system. (make sure to create backup copy of the file before any manual edits). Usually server restart is not necessary for the changes to take effect.
VCS root with id "XXX" does not exist
The build configuration or template reference a VCS root which is not defined in the system.
Remedy actions: Restore the VCS root or create a new VCS root with the id noted or edit the file noted in the message to remove the reference to the VCS root.
TeamCity installation problems
If the TeamCity Web UI cannot be accessed after installation, you might be running TeamCity on a port that is already in use by another program. Check and configure your TeamCity installation.
Problems with TeamCity NuGet Feed
If you are experiencing issues with partial TeamCity NuGet Feed, i.e. missing NuGet packages etc., you might have to reindex the TeamCity NuGet Feed.
To force TeamCity to reindex all available packages and reset the NuGet package list, navigate to the server Administration| Diagnostics | Caches and use the buildsMetadata Reset link.
For earlier versions, refer to this section.
Problems with .Net-related TeamCity Tools
Startup performance issues
After upgrade to TeamCity 9.0 or later, .NET Framework below version 4.0 installed on TeamCity agents may cause performance issues of .Net-related TeamCity tools due to Code access security (CAS) policy imposed by Microsoft.
To solve the issue, use one of the options:
Add the following setting described in the Microsoft documentation to the
machine.configfile on all agents:
<configuration> <runtime> <generatePublisherEvidence enabled="false"/> </runtime> </configuration>
You can modify the machine.config file as described in this external blog post and pass this config file to all agents, e.g. using a custom script.
Alternatively, upgrade .Net Framework on the TeamCity agents to version 4.0 and above. Details are available in the Microsoft documentation.