TeamCity "Build agent disconnected" during a build in CI

By Daniel Zoghalchali·Latchkey

The server stopped receiving heartbeats from the agent while the build was running. TeamCity marks the agent disconnected and either re-queues the build or fails it, depending on configuration.

What this error means

The build log ends abruptly and the agent shows "Build agent 'Agent-1' was disconnected" or "Agent has unexpectedly disconnected from the server". The agent may reconnect moments later.

Build agent 'Agent-1' was disconnected during the build.
The build has been re-added to the queue.

Common causes

Network interruption between agent and server

A dropped connection, proxy timeout, or DNS blip stops heartbeats, so the server declares the agent disconnected.

The agent process was killed or ran out of resources

An OOM kill, a crash, or a host reboot terminates the agent process, cutting the connection mid-build.

How to fix it

Confirm the agent can reach the server

1. On the agent host, check that serverUrl in buildAgent.properties resolves and is reachable.
2. Review the agent log at <agent>/logs/teamcity-agent.log for the disconnect cause.
3. Restart the agent service so it re-registers with the server.

# <agent>/conf/buildAgent.properties
serverUrl=https://teamcity.example.com

Give the agent host enough memory and stable networking

Raise the agent JVM and host memory so it is not OOM-killed, and place the agent on a stable network path to the server.

How to prevent it

• Monitor agent host memory and CPU so processes are not killed under load.
• Keep a stable, low-latency network path between agents and the server.
• Enable build re-queue on disconnect so a transient drop does not lose work.

Frequently asked questions

Related guides

References

• GitHub Actions documentation