ZMS: Troubleshoot Agent Deployment
Keywords
agent deployment, agent enrollment, agent disconnected, provisioning key, nonce, TOTP, agent version, agent connectivity, agent group, agent health, microsegmentation agent, agent upgrade, agent troubleshoot
Overview
Troubleshoot Zscaler Microsegmentation (ZMS) agent deployment, enrollment, and connectivity issues. This skill systematically investigates agent fleet health, identifies disconnected or outdated agents, verifies agent group configuration, checks provisioning key availability, and retrieves enrollment credentials. It covers the full agent lifecycle from initial provisioning through ongoing health monitoring.
The ZMS API is a GraphQL endpoint on OneAPI. The full API supports both Query (read) and Mutation (write) operations for agents, agent groups, and nonces:
- Query operations (available via MCP):
agents,agentGroups,AgentConnectionStatusStatisticsConnection,agentVersionStatistics,nonces,nonce - Mutation operations (not yet in MCP, available via API/portal):
agentUpdate,agentDelete,agentGroupCreate/Update/Delete,agentGroupUpgradeStatusReset,nonceCreate/Update/Delete,nonceWithAgentGroupCreate
Use this skill when: An administrator reports agents not connecting, enrollment failures, version mismatches, or needs to set up provisioning for new agent deployments.
Important:
- All ZMS tools require
ZSCALER_CUSTOMER_IDto be set as an environment variable. - All current MCP tools are read-only (Query operations). Write operations (create/update/delete agents, groups, nonces) must be performed through the Zscaler admin portal or the ZMS API directly.
- GraphQL errors may return HTTP 200 with errors in the response body — always check for the
errorsfield.
Workflow
Follow this 6-step process to troubleshoot agent deployment.
Step 1: Identify the Problem
Gather from the administrator:
Required:
- What is the symptom? (agent not connecting, enrollment failure, version mismatch, missing agent)
- Which agents or hosts? (hostname, IP, agent group)
- When did the issue start?
Helpful:
- Is this a new deployment or an existing agent?
- Cloud provider (AWS, Azure, GCP, on-premises)?
- OS type and version?
- Any recent infrastructure changes?
- Error messages from the agent installer?
Step 2: Check Overall Fleet Health
Get connection status statistics:
Step 4: Verify Agent Group Configuration
List agent groups:


