{"record":{"id":"ac759a2f1525e588","repo":"alibaba/spring-ai-alibaba","slug":"please-use-getagentcard-agentname-first","errorCode":null,"errorMessage":"Please use getAgentCard(agentName) first.","messagePattern":"Please use getAgentCard\\(agentName\\) first\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/registry/nacos/discovery/NacosAgentCardProvider.java","lineNumber":54,"sourceCode":" *\n * @author xiweng.yy\n */\npublic class NacosAgentCardProvider implements AgentCardProvider {\n\n\tprivate static final Logger LOGGER = LoggerFactory.getLogger(NacosAgentCardProvider.class);\n\n\tprivate final A2aService a2aService;\n\n\tprivate AgentCardWrapper agentCard;\n\n\tpublic NacosAgentCardProvider(A2aService a2aService) {\n\t\tthis.a2aService = a2aService;\n\t}\n\n\t@Override\n\tpublic AgentCardWrapper getAgentCard() {\n\t\tif (null == agentCard) {\n\t\t\tthrow new IllegalStateException(\"Please use getAgentCard(agentName) first.\");\n\t\t}\n\t\treturn agentCard;\n\t}\n\n\t@Override\n\tpublic AgentCardWrapper getAgentCard(String agentName) {\n\t\ttry {\n\t\t\tAgentCard nacosAgentCard = a2aService.getAgentCard(agentName);\n\t\t\tagentCard = new NacosAgentCardWrapper(AgentCardConverterUtil.convertToA2aAgentCard(nacosAgentCard));\n\t\t\ta2aService.subscribeAgentCard(agentName, new AbstractNacosAgentCardListener() {\n\t\t\t\t@Override\n\t\t\t\tpublic void onEvent(NacosAgentCardEvent event) {\n\t\t\t\t\tAgentCard newAgentCard = event.getAgentCard();\n\t\t\t\t\tif (LOGGER.isDebugEnabled()) {\n\t\t\t\t\t\tLOGGER.debug(\"Received new Agent Card: {}\", JacksonUtils.toJson(newAgentCard));\n\t\t\t\t\t}\n\t\t\t\t\tagentCard.setAgentCard(AgentCardConverterUtil.convertToA2aAgentCard(newAgentCard));\n\t\t\t\t}","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-a2a-nacos/src/main/java/com/alibaba/cloud/ai/a2a/registry/nacos/discovery/NacosAgentCardProvider.java#L36-L72","documentation":"NacosAgentCardProvider supports both a no-arg getAgentCard() and a by-name getAgentCard(agentName). The no-arg variant returns a cached agentCard field; if the caller never invoked the by-name variant (or otherwise populated the cache) the provider throws IllegalStateException instructing the caller to call getAgentCard(agentName) first. This is a usage-order contract: the parameterless accessor only reads a pre-fetched card.","triggerScenarios":"Calling getAgentCard() (no arguments) on NacosAgentCardProvider before any successful call to getAgentCard(agentName) has populated the internal agentCard field.","commonSituations":"Framework or application code that resolves a single agent card from the A2A registry without knowing a name, relying on default discovery while the provider was constructed without an initial card; ordering issues where discovery happens after the card is requested.","solutions":["Call getAgentCard(agentName) with the target agent's name first, then use the returned card (or call the no-arg getter afterwards).","If you need nameless lookup, query the Nacos registry for available agent names first and pass one to getAgentCard(String).","Inject/configure the AgentCardWrapper so the provider's agentCard field is populated at construction if single-agent mode is intended.","Wrap the no-arg call in try-catch for IllegalStateException and fall back to the by-name API."],"exampleFix":"// before\nAgentCardWrapper card = provider.getAgentCard(); // IllegalStateException\n// after\nAgentCardWrapper card = provider.getAgentCard(\"my-agent\");","handlingStrategy":"type-guard","validationCode":"AgentCardWrapper card = provider.getAgentCard(agentName); // fetch first\nif (card != null) { /* safe to use card / provider.getAgentCard() */ }","typeGuard":"AgentCardWrapper safeGetCard(NacosAgentCardProvider p, String name) {\n    try { return p.getAgentCard(); }\n    catch (IllegalStateException e) { return p.getAgentCard(name); }\n}","tryCatchPattern":"try {\n    card = provider.getAgentCard();\n} catch (IllegalStateException e) {\n    card = provider.getAgentCard(agentName);\n}","preventionTips":["Prefer the by-name getAgentCard(agentName) API; it always works","Only use the no-arg getter after a successful by-name fetch","Configure the provider's initial card when running single-agent mode"],"tags":["a2a","nacos","usage-order","service-discovery"],"backgroundTag":"invalid-state-transition","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}