Summary
In HCP Terraform, workspaces configured to use Terraform Cloud Agents may fail to start runs and display the message:
“No available agents in the selected agent pool.”This issue occurs when no agent in the assigned pool is online, connected, or capable of pulling the run. This article explains the root causes and how to restore agent connectivity.
Symptoms
Workspaces using an agent execution mode may show:
• A Run fails to start and stays in Pending or Queued state.
• The run details show: “Waiting for an available agent…”
• The Agent Pools page shows: 0 agents connected, or agents showing as offline, disconnected, or unhealthy.
• The local machine or VM running the Agent logs messages like: “Unable to authenticate agent token”, “Agent listener disconnected”, “Dial tcp … connection refused”.
Cause
A workspace requires at least one active agent in its assigned agent pool to execute runs. Runs may fail or hang if:
• The agent service is not running on the server/VM/container
• The agent token used is invalid, expired, or deleted
• Network restrictions block outbound traffic
• The agent binary has not been updated to match protocol requirements
• The VM hosting the agent was shut down, restarted, or destroyed
• The workspace points to an agent pool that has no online agents
Solution
Step 1: Verify the Agent Pool
1. In HCP Terraform, go to Settings → Agents → Agent Pools.
2. Select the agent pool assigned to the failing workspace.
3. Check whether any agents are listed as Connected.
4. If none are online, proceed with the next steps.
Step 2: Restart the Agent on the Host Machine
Depending on how you installed the agent:
Linux Systemd
sudo systemctl restart tfrun-agent
sudo systemctl status tfrun-agent
Docker
docker restart <container-name>
docker logs <container-name>
Bare Executable
Re-run the terraform-agent binary with the agent token.
After restarting, return to the HCP Terraform UI and verify that the agent shows as Connected.
Step 3: Confirm the Agent Token Is Valid
Invalid or missing tokens are a common cause.
1. In HCP Terraform, go to Settings → Agents → Agent Tokens.
2. Ensure the token the host is using still exists.
3. If it was deleted or rotated, create a new agent token.
4. Update your host configuration with the new token and restart the agent.
Step 4: Check Network Requirements
Agents require outbound access to:
• *.terraform.io
• https://app.terraform.io
• Ports 443 (HTTPS) and sometimes 8800 depending on installation
Verify that firewalls or proxies are not blocking outbound connections.
Step 5: Validate Workspace Agent Pool Assignment
Runs will never start if the workspace is assigned to an empty agent pool.
1. Open the workspace → Settings → Execution Mode.
2. Confirm that execution mode is Agent, and the correct agent pool is selected.
3. If the wrong pool is selected, switch to a pool with active agents.
Additional Considerations
If You Recently Rebuilt the Agent Host
• Ensure the agent is set to start automatically on boot
(systemd service or container restart policy).
If Using Docker
Use the official entrypoint and environment variables:
docker run \
-e TFC_AGENT_TOKEN=<token> \
hashicorp/tfc-agent:latest
If Agents Flap Online/Offline
This may indicate:
• Resource exhaustion on the host
• Aggressive proxy timeouts
• Network instability
• Outdated agent versions
Update the agent binary and check host CPU/memory.