How to Fix Azure DevOps Agent Offline

A deployment is ready, the approval is complete, and the release sits in the queue. The application package is fine, but the self-hosted build server stopped communicating after overnight maintenance.

An Azure DevOps agent offline issue usually points to the agent host, listener service, outbound connectivity, or agent registration—not the application deployment code. Reinstalling immediately can erase useful evidence without fixing the underlying problem.

This guide walks through a practical troubleshooting sequence to restore communication, verify pipeline execution, and reduce repeat outages.

Identify the Azure DevOps Agent Offline Failure

An agent is the worker that executes pipeline jobs. A self-hosted agent runs on infrastructure your team manages, such as an Azure virtual machine, an on-premises server, or a container.

Start in Organization settings → Agent pools → select the pool → Agents. Record the agent name, status, version, and whether it is enabled.

Distinguish these conditions before changing anything:

A demand is a job requirement, such as a particular installed tool. An online agent that cannot satisfy demands is not an offline agent.

This guide focuses on self-hosted agents connected to Azure DevOps Services. Microsoft-hosted agents use service-managed, temporary workers; you do not repair them by restarting a Windows service on your own server.

Pro Tip: I separate “cannot communicate” from “cannot receive work” before touching the host. Those problems can look similar in a release queue but require different fixes.

Step 1: Check the Host Before Restarting the Agent

Confirm the machine exists, is running, and has not entered sleep mode. For Azure virtual machines, check power state, recent maintenance, boot diagnostics, and administrative changes.

az vm get-instance-view \
  --resource-group <resource-group-name> \
  --name <agent-vm-name> \
  --query "instanceView.statuses[].{Code:code,Status:displayStatus}" \
  --output table

This command retrieves the VM’s instance status. --resource-group identifies its management container, while --name selects the agent VM.

A running VM does not prove the operating system or agent is healthy. Connect through your approved administrative path and inspect:

• Available disk space, especially the agent work directory.
• Memory pressure and CPU saturation.
• Recent reboots and operating-system updates.
• Endpoint-protection events.
• Container termination events, if applicable.

Microsoft specifically recommends checking resource utilization when a pipeline reports that it stopped hearing from an agent. CPU starvation, exhausted memory, or process termination can interrupt communication.

If the VM itself will not boot, troubleshoot the Azure VM not starting problem before repairing the agent.

Change warning: starting a deallocated VM resumes compute charges. Restarting a VM can interrupt other agents or workloads sharing that host.

Pro Tip: I capture the failure time and host events before restarting anything. That timestamp often connects the outage to patching, a full disk, or a resource-heavy build.

Step 2: Inspect and Restart the Agent Service

A self-hosted agent must have an active listener process. Installing the agent as a service avoids dependence on an interactive user session.

Windows agents

Run PowerShell with appropriate administrative permissions:

Get-Service -Name 'vstsagent*' |
    Select-Object Name, DisplayName, Status, StartType

Get-Service lists matching Azure Pipelines agent services. Inspect the exact service name because one machine may contain several installations.

For one confirmed service:

$AgentServiceName = '<exact-agent-service-name>'
Start-Service -Name $AgentServiceName
Get-Service -Name $AgentServiceName

Start-Service starts a stopped service. The final command checks its local state; confirm the portal status separately.

If the service is running but unresponsive, preserve logs before restarting it:

$AgentServiceName = '<exact-agent-service-name>'
Restart-Service -Name $AgentServiceName

Restart-Service stops and starts only the specified service.

Interruption warning: restarting an agent during a job can fail that job. Disable the agent to prevent new assignments and let existing work finish when possible.

Linux agents

From the agent installation directory:

cd /opt/azdo-agent
sudo ./svc.sh status

svc.sh status checks the installed service. Replace /opt/azdo-agent with the actual installation directory.

cd /opt/azdo-agent
sudo ./svc.sh start

svc.sh start starts the configured service. If it fails immediately, inspect the system service journal and agent logs instead of repeatedly restarting it.

For an interactive diagnostic run, stop the service first. Do not launch another listener against the same agent configuration while its service remains active.

Pro Tip: I check the service identity when an agent works interactively but fails as a service. The two sessions may have different proxy settings, certificate trust, and directory permissions.

Step 3: Read Logs to Find the Actual Failure

The agent’s _diag directory contains diagnostic files. Listener logs help explain connection and startup failures; worker logs help investigate jobs that already started.

For a Windows installation:

$AgentRoot = 'C:\azdo-agent'
Get-ChildItem -Path "$AgentRoot\_diag" -File |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 10 Name, LastWriteTime, Length

Get-ChildItem lists diagnostic files. Sorting by LastWriteTime identifies files updated around the outage.

Read one relevant file:

$AgentLogPath = '<full-path-to-selected-agent-log>'
Get-Content -Path $AgentLogPath -Tail 150

Get-Content -Tail 150 displays the final 150 lines without loading the entire log.

Look for patterns rather than isolated messages:

Redact secrets and sensitive infrastructure details before sharing logs. Avoid broad HTTP tracing unless necessary because detailed traces can contain sensitive information.

Pro Tip: I investigate the first meaningful error after a known-good connection. Later messages are often consequences of the original failure.

Step 4: Repair Network, Proxy, and Certificate Problems

Self-hosted agents initiate communication with Azure DevOps. They need outbound connectivity; opening an inbound listener port is not the standard fix.

From a Windows agent host:

Resolve-DnsName -Name dev.azure.com
Test-NetConnection -ComputerName dev.azure.com -Port 443

Resolve-DnsName checks DNS resolution. Test-NetConnection -Port 443 checks whether a TCP connection can reach the HTTPS port.

Passing these tests does not prove authentication, TLS negotiation, or every required endpoint works. Repository checkout, artifact downloads, package feeds, and agent updates can require additional destinations.

Check the complete outbound path

For an Azure VM, inspect its virtual network, routing, outbound network security group rules, Azure Firewall policies, and proxy configuration. A network security group filters traffic; it does not configure an application proxy.

Use the organization’s approved Azure DevOps endpoint allowlist. Avoid permanently relying on one resolved IP address.

If traffic passes through TLS inspection, the service account must trust the approved certificate chain. Do not disable certificate verification to make the error disappear.

A private endpoint provides private access to a supported Azure resource. It does not automatically provide private access to Azure DevOps Services. An agent may need both private connectivity to deployment targets and controlled outbound access to Azure DevOps.

For network-rule fundamentals, see what an Azure network security group does.

Pro Tip: I repeat connectivity checks under the service’s effective configuration. A browser working under my administrator account does not prove the agent can use the same proxy.

Step 5: Check Authentication Before Re-registering

Keep three identities separate:

1. The operating-system account running the agent.
2. The agent’s registered identity communicating with Azure DevOps.
3. The Azure service connection used by deployment tasks.

An expired Azure deployment credential generally causes a task authentication failure, not an offline agent.

Likewise, do not assume an expired personal access token caused an established agent to disconnect. A registration PAT is used during initial configuration, not subsequent agent communication.

Check for deleted agent records, damaged local configuration, organization changes, revoked access, or explicit authentication errors.

If re-registration becomes necessary:

1. Preserve diagnostic logs and document pool settings.
2. Disable or drain the old agent.
3. Use supported removal and configuration scripts.
4. Register with the intended organization and pool.
5. Install and start the service.