{"record":{"id":"3210b4524bc85e36","repo":"alibaba/nacos","slug":"invalid-param-3210b4","errorCode":"INVALID_PARAM","errorMessage":"Required parameter `agentSpecName` not present","messagePattern":"Required parameter `agentSpecName` not present","errorType":"validation","errorClass":"NacosException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/com/alibaba/nacos/client/ai/cache/NacosAgentSpecCacheHolder.java","lineNumber":97,"sourceCode":"        this.agentSpecCache = new ConcurrentHashMap<>(4);\n        this.updateTaskMap = new ConcurrentHashMap<>(4);\n        this.updaterExecutor = new ScheduledThreadPoolExecutor(1,\n            new NameThreadFactory(\"com.alibaba.nacos.client.ai.agentspec.updater\"));\n        this.updateIntervalMillis = properties.getLong(\n            AiConstants.AI_AGENTSPEC_CACHE_UPDATE_INTERVAL,\n            AiConstants.DEFAULT_AI_CACHE_UPDATE_INTERVAL);\n    }\n    \n    /**\n     * Query agent spec synchronously (no subscription).\n     *\n     * @param agentSpecName name of agent spec\n     * @return AgentSpec object, null if not found\n     * @throws NacosException if error occurs\n     */\n    public AgentSpec queryAgentSpec(String agentSpecName) throws NacosException {\n        if (StringUtils.isBlank(agentSpecName)) {\n            throw new NacosException(NacosException.INVALID_PARAM,\n                \"Required parameter `agentSpecName` not present\");\n        }\n        try {\n            AgentSpecQueryResponse response =\n                aiClientProxy.queryAgentSpec(agentSpecName, null, null, null);\n            return response.getAgentSpec();\n        } catch (NacosException e) {\n            if (e.getErrCode() == NacosException.NOT_FOUND) {\n                return null;\n            }\n            throw e;\n        }\n    }\n    \n    /**\n     * Subscribe to agent spec changes and start polling.\n     *\n     * <p>Performs the initial query synchronously and primes the MD5 cache; subsequent polls","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/ai/cache/NacosAgentSpecCacheHolder.java#L79-L115","documentation":"Thrown by NacosAgentSpecCacheHolder.queryAgentSpec when agentSpecName is blank (null, empty, or whitespace). queryAgentSpec is a synchronous one-shot lookup with no subscription; an empty name cannot identify a resource so it is rejected as INVALID_PARAM before any network call. Catching NOT_FOUND from the proxy is re-mapped to a null return, so this error only fires on the blank-name guard.","triggerScenarios":"Calling queryAgentSpec(\"\"), queryAgentSpec(null), or queryAgentSpec with a value that is only whitespace. Also when a variable holding the spec name was never populated (default null).","commonSituations":"Configuration property for the agent spec name left unset; upstream producer emitted an empty name; field deserialized from JSON with a missing/blank name attribute.","solutions":["Validate agentSpecName is non-blank before calling queryAgentSpec.","Load the spec name from configuration with a required/checked default.","If the name legitimately may be absent, skip the call rather than passing an empty value."],"exampleFix":"// before\nAgentSpec spec = cache.queryAgentSpec(specName);\n// after\nif (StringUtils.isBlank(specName)) {\n    throw new IllegalArgumentException(\"agentSpecName is required\");\n}\nAgentSpec spec = cache.queryAgentSpec(specName);","handlingStrategy":"validation","validationCode":"if (StringUtils.isBlank(agentSpecName)) {\n    throw new IllegalArgumentException(\"agentSpecName is required\");\n}\ncache.queryAgentSpec(agentSpecName);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Source agentSpecName from validated configuration.","Fail fast at startup if the required name property is missing.","Unit-test the blank/empty name case at the boundary."],"tags":["ai","agent-spec","validation","invalid-param"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}