pinpoint-apm/pinpoint · error · ResponseStatusException

Cannot find suitable agent

Error message

Cannot find suitable agent(${applicationName}/${agentId})

What it means

After the activeThreadDump feature gate passes, getClusterKey asks AgentService for a ClusterKey matching the given applicationName and agentId. This error is thrown when no suitable agent is registered in the cluster (the lookup returns null), meaning Pinpoint Web cannot find a live channel/registration for that agent to request a thread dump from.

Solutions

1. Verify the agentId and applicationName are correct and the agent is currently running (check it appears in the agent list / inspector page)
2. Restart the agent so it re-registers with the cluster, and confirm the agent's collector connection is healthy
3. Check Pinpoint Web cluster configuration (cluster.enable, cluster.zookeeper.address, cluster.web.tcp.port) so Web participates in the same ZooKeeper cluster as Collector/agents
4. Retry shortly after agent startup — registration may lag a few seconds

Example fix

// before
GET /getActiveThreadDump?applicationName=MyApp&agentId=old-agent-id
// after — confirm current agentId from the agent list first
GET /getActiveThreadDump?applicationName=MyApp&agentId=current-agent-id

const agents = await api.getAgentList(applicationName);
const target = agents.find(a => a.agentId === agentId && a.status === 'running');
if (!target) throw new Error(`Agent ${agentId} is not currently running`);

try {
  return await api.getActiveThreadDump({ applicationName, agentId });
} catch (e) {
  if (e.status === 500 && String(e.message).startsWith('Cannot find suitable agent')) {
    await sleep(2000); // allow agent re-registration
    return retryOnce(() => api.getActiveThreadDump({ applicationName, agentId }));
  }
  throw e;
}

When it happens

Trigger: Requesting an active thread dump for an agentId that is not currently connected/registered in the Pinpoint cluster — wrong applicationName/agentId combination, the agent has shut down or crashed, the agent is behind a network partition from ZooKeeper/cluster channel, or the agentId contains a typo.

Common situations: Agent was restarted with a different agentId; stale UI still listing a dead agent; agents connecting only to the Collector while Web's cluster channel is misconfigured (cluster.zookeeper.address / web cluster enable flags); time skew between requesting and the agent's registration expiry.

Related errors

• Agent already started.
• Cannot stop agent. Current status =
• classPath not found. classPath:+classPath
• Disable activeThreadDump option…
• Error opening stream :

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/99db7d75cc589f96. Report an issue: GitHub.

Appendix: source

Thrown at web/src/main/java/com/navercorp/pinpoint/web/authorization/controller/ActiveThreadDumpController.java:125

        return CodeResult.ok(new ThreadDumpResult(
                activeThreadDumpList,
                response.getType(),
                response.getSubType(),
                response.getVersion()
        ));
    }

    private ClusterKey getClusterKey(String applicationName, String agentId) {
        if (!this.webProperties.isEnableActiveThreadDump()) {
            throw new ResponseStatusException(
                    HttpStatus.INTERNAL_SERVER_ERROR,
                    "Disable activeThreadDump option. 'config.enable.activeThreadDump=false'"
            );
        }

        final ClusterKey clusterKey = this.agentService.getClusterKey(applicationName, agentId);
        if (clusterKey == null) {
            throw new ResponseStatusException(
                    HttpStatus.INTERNAL_SERVER_ERROR,
                    String.format("Cannot find suitable agent(%s/%s)", applicationName, agentId)
            );
        }
        return clusterKey;
    }

}

View on GitHub (pinned to 744c3d3075)