alibaba/nacos · warning · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

Version is required for agentspec version detail

What it means

Thrown by AgentSpecOperationServiceImpl.getAgentSpecVersionDetail when the version parameter is blank (null or whitespace). The AgentSpec meta must exist first; only then is the version requirement enforced. Reported as PARAMETER_MISSING (HTTP 400).

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agentspecs/AgentSpecOperationServiceImpl.java:235

        return detail;
    }
    
    /**
     * Get the full content of a specific AgentSpec version by reading from storage.
     */
    @Override
    public AgentSpec getAgentSpecVersionDetail(String namespaceId, String agentSpecName,
        String version)
        throws NacosException {
        AiResource meta =
            resourceManager.findMeta(namespaceId, agentSpecName, RESOURCE_TYPE_AGENTSPEC);
        if (meta == null) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
                "AgentSpec not found: " + agentSpecName);
        }
        resourceManager.ensureReadableOrNotFound(meta, "AgentSpec not found: " + agentSpecName);
        if (StringUtils.isBlank(version)) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "Version is required for agentspec version detail");
        }
        AiResourceVersion versionRow = resourceManager.findVersion(namespaceId, agentSpecName,
            RESOURCE_TYPE_AGENTSPEC, version);
        if (versionRow == null) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.RESOURCE_NOT_FOUND,
                "AgentSpec version not found: " + agentSpecName + "@" + version);
        }
        return loadAgentSpecFromStorage(namespaceId, agentSpecName, version,
            versionRow.getStorage());
    }
    
    /**
     * Get agentspec version metadata without resource content. Only reads the main config file (manifest.json) and
     * builds resource list from the reference entries, skipping all resource file IO.
     */
    @Override
    public AgentSpec getAgentSpecVersionMeta(String namespaceId, String agentSpecName,

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Pass an explicit, non-blank version string (e.g. '1' or '1.0.0') in the request.
2. Validate the version parameter client-side before issuing the request.
3. If you want the latest version without specifying it, use the label-based query endpoint ('latest') instead of the explicit version-detail endpoint.

Example fix

// before
service.getAgentSpecVersionDetail(ns, "my-spec", ""); // blank version

// after
service.getAgentSpecVersionDetail(ns, "my-spec", "1");

if (StringUtils.isBlank(version)) {
    throw new IllegalArgumentException("version is required for version detail");
}

When it happens

Trigger: Calling the version-detail API with an omitted, empty, or whitespace-only version query parameter.

Common situations: Client omits the version field expecting a default; a form binding fails to populate version; a URL template leaves the version segment empty.

Related errors

• 10000
• 20002
• 10000
• 10000
• Version cannot be blank

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