TeamCity server "database connection" failure in CI
The TeamCity server stores all configuration and build history in an external database. When it cannot connect (wrong credentials, unreachable host, or an exhausted connection pool), the server reports a database error and builds cannot proceed.
What this error means
The server startup or runtime logs show "Cannot connect to the database" or "Error while connecting to database", and the UI is unavailable or read-only.
Failed to connect to the database:
com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failureCommon causes
Wrong connection settings or credentials
The database.properties URL, user, or password is wrong, or the driver is missing, so the server cannot authenticate to the database.
The database is unreachable or overloaded
Network issues, a stopped database, or an exhausted connection pool break the link between server and database.
How to fix it
Verify database connection settings
- Check
<data-dir>/config/database.propertiesfor the correct URL, user, and password. - Confirm the database host is reachable from the server and the JDBC driver is present.
- Restart the server and watch
teamcity-server.logfor a clean connect.
# <data-dir>/config/database.properties
connectionUrl=jdbc:mysql://db-host:3306/teamcity
connectionProperties.user=teamcityRestore database availability and pool size
Bring the database back up, fix networking, and size the connection pool so peak load does not exhaust connections.
How to prevent it
- Monitor database reachability and connection pool usage.
- Keep database credentials and the JDBC driver current with the server version.
- Back up the data directory and database together.