alibaba/nacos · error · NacosException

INVALID_PARAM

INVALID_PARAM

Error message

Required parameter `agentSpecName` not present

What it means

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.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/ai/cache/NacosAgentSpecCacheHolder.java:97

        this.agentSpecCache = new ConcurrentHashMap<>(4);
        this.updateTaskMap = new ConcurrentHashMap<>(4);
        this.updaterExecutor = new ScheduledThreadPoolExecutor(1,
            new NameThreadFactory("com.alibaba.nacos.client.ai.agentspec.updater"));
        this.updateIntervalMillis = properties.getLong(
            AiConstants.AI_AGENTSPEC_CACHE_UPDATE_INTERVAL,
            AiConstants.DEFAULT_AI_CACHE_UPDATE_INTERVAL);
    }
    
    /**
     * Query agent spec synchronously (no subscription).
     *
     * @param agentSpecName name of agent spec
     * @return AgentSpec object, null if not found
     * @throws NacosException if error occurs
     */
    public AgentSpec queryAgentSpec(String agentSpecName) throws NacosException {
        if (StringUtils.isBlank(agentSpecName)) {
            throw new NacosException(NacosException.INVALID_PARAM,
                "Required parameter `agentSpecName` not present");
        }
        try {
            AgentSpecQueryResponse response =
                aiClientProxy.queryAgentSpec(agentSpecName, null, null, null);
            return response.getAgentSpec();
        } catch (NacosException e) {
            if (e.getErrCode() == NacosException.NOT_FOUND) {
                return null;
            }
            throw e;
        }
    }
    
    /**
     * Subscribe to agent spec changes and start polling.
     *
     * <p>Performs the initial query synchronously and primes the MD5 cache; subsequent polls

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Validate agentSpecName is non-blank before calling queryAgentSpec.
2. Load the spec name from configuration with a required/checked default.
3. If the name legitimately may be absent, skip the call rather than passing an empty value.

Example fix

// before
AgentSpec spec = cache.queryAgentSpec(specName);
// after
if (StringUtils.isBlank(specName)) {
    throw new IllegalArgumentException("agentSpecName is required");
}
AgentSpec spec = cache.queryAgentSpec(specName);

if (StringUtils.isBlank(agentSpecName)) {
    throw new IllegalArgumentException("agentSpecName is required");
}
cache.queryAgentSpec(agentSpecName);

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• INVALID_PARAM
• INVALID_PARAM
• INVALID_PARAM
• 10000
• 20002

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/3210b4524bc85e36. Report an issue: GitHub.