{"record":{"id":"99db7d75cc589f96","repo":"pinpoint-apm/pinpoint","slug":"cannot-find-suitable-agent-applicationname-ag","errorCode":null,"errorMessage":"Cannot find suitable agent(${applicationName}/${agentId})","messagePattern":"Cannot find suitable agent\\((.+?)/(.+?)\\)","errorType":"http","errorClass":"ResponseStatusException","httpStatus":500,"severity":"error","filePath":"web/src/main/java/com/navercorp/pinpoint/web/authorization/controller/ActiveThreadDumpController.java","lineNumber":125,"sourceCode":"        return CodeResult.ok(new ThreadDumpResult(\n                activeThreadDumpList,\n                response.getType(),\n                response.getSubType(),\n                response.getVersion()\n        ));\n    }\n\n    private ClusterKey getClusterKey(String applicationName, String agentId) {\n        if (!this.webProperties.isEnableActiveThreadDump()) {\n            throw new ResponseStatusException(\n                    HttpStatus.INTERNAL_SERVER_ERROR,\n                    \"Disable activeThreadDump option. 'config.enable.activeThreadDump=false'\"\n            );\n        }\n\n        final ClusterKey clusterKey = this.agentService.getClusterKey(applicationName, agentId);\n        if (clusterKey == null) {\n            throw new ResponseStatusException(\n                    HttpStatus.INTERNAL_SERVER_ERROR,\n                    String.format(\"Cannot find suitable agent(%s/%s)\", applicationName, agentId)\n            );\n        }\n        return clusterKey;\n    }\n\n}\n","sourceCodeStart":107,"sourceCodeEnd":134,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/web/src/main/java/com/navercorp/pinpoint/web/authorization/controller/ActiveThreadDumpController.java#L107-L134","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the agentId and applicationName are correct and the agent is currently running (check it appears in the agent list / inspector page)","Restart the agent so it re-registers with the cluster, and confirm the agent's collector connection is healthy","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","Retry shortly after agent startup — registration may lag a few seconds"],"exampleFix":"// before\nGET /getActiveThreadDump?applicationName=MyApp&agentId=old-agent-id\n// after — confirm current agentId from the agent list first\nGET /getActiveThreadDump?applicationName=MyApp&agentId=current-agent-id","handlingStrategy":"retry","validationCode":"const agents = await api.getAgentList(applicationName);\nconst target = agents.find(a => a.agentId === agentId && a.status === 'running');\nif (!target) throw new Error(`Agent ${agentId} is not currently running`);","typeGuard":null,"tryCatchPattern":"try {\n  return await api.getActiveThreadDump({ applicationName, agentId });\n} catch (e) {\n  if (e.status === 500 && String(e.message).startsWith('Cannot find suitable agent')) {\n    await sleep(2000); // allow agent re-registration\n    return retryOnce(() => api.getActiveThreadDump({ applicationName, agentId }));\n  }\n  throw e;\n}","preventionTips":["Fetch the live agent list and pick a running agentId rather than caching agent IDs","Confirm Web and Collector share the same ZooKeeper cluster configuration","Retry with a short backoff right after agent startup","Monitor agent heartbeat/registration to catch dead agents before issuing thread dumps"],"tags":["agent","cluster","resource-not-found","thread-dump"],"backgroundTag":"agent-not-found","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}