TeamCity agent upgrade stuck or failed after server update in CI

By Kaveh Alemi·Latchkey

After a server upgrade, agents automatically download the matching agent distribution and plugins. If the download or unpack fails, the agent stays in "Upgrading" and does not run builds until it completes.

What this error means

Agents show status "Upgrading" indefinitely, or the agent log reports a failure downloading or applying the new distribution after the server was updated.

Agent is upgrading...
Failed to download plugin from the server: Connection reset
Upgrade will be retried.

Common causes

The agent cannot download the new distribution

A network interruption or proxy issue stops the agent from fetching the updated agent files from the server after an upgrade.

A version or file mismatch on the agent

Leftover files from a previous version, or insufficient permissions to write the agent directory, block the upgrade from applying cleanly.

How to fix it

Let the agent re-download and restart it

1. Confirm the agent can reach the server URL over the network.
2. Stop the agent, remove the <agent>/update staging directory, and start it again.
3. Watch teamcity-agent.log until the agent reconnects and reports the new version.

# on the agent host
<agent>/bin/agent.sh stop
rm -rf <agent>/update
<agent>/bin/agent.sh start

Reinstall the agent from the server distribution

If the upgrade will not apply, download a fresh agent zip from the server Agents page and reinstall, preserving conf/buildAgent.properties.

How to prevent it

• Ensure agents have a reliable network path to the server for upgrades.
• Give the agent user write access to its own installation directory.
• Upgrade agents in a maintenance window and confirm each reconnects.

Frequently asked questions

Related guides

References

• GitHub Actions documentation