alibaba/nacos · error · Error

agent.versionRequired

Error message

agent.versionRequired

What it means

Thrown by the newAgent editor's data-loading effect when the route is in 'draft-edit' mode but the `version` query parameter is absent. In draft-edit mode the editor must fetch a specific agent version via agentApi.getVersion(), which requires both agentName and version; without a version the lookup is impossible, so the effect throws a localized 'agent.versionRequired' error before calling the API.

Source

Thrown at console-ui-next/src/pages/newAgent/index.tsx:189

        return;
      }
      if (!queryAgentName) {
        toast.error(t('agent.nameRequired'));
        setLoading(false);
        return;
      }
      try {
        if (mode === 'metadata') {
          const response = await agentApi.getAgent({
            namespaceId,
            agentName: queryAgentName,
          });
          if (active) {
            setValues(metadataToEditorValues(response.data.agent));
          }
        } else if (mode === 'draft-edit') {
          if (!queryVersion) {
            throw new Error(t('agent.versionRequired'));
          }
          const response = await agentApi.getVersion({
            namespaceId,
            agentName: queryAgentName,
            version: queryVersion,
          });
          if (active) {
            setValues((current) => ({
              ...current,
              agentName: queryAgentName,
              version: queryVersion,
              ...callInterfacesToEditorValues(response.data.callInterfaces),
              changeDescription: response.data.changeDescription || '',
            }));
          }
        }
      } catch (error) {
        toast.error(error instanceof Error ? error.message : t('agent.loadFailed'));

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Include the `version` query parameter when navigating to draft-edit mode (e.g. ?mode=draft-edit&agentName=X&version=1.0.0).
2. Add a route guard that redirects away from draft-edit when version is missing, instead of letting the effect throw.
3. If versionless editing is intended, switch to mode=metadata which does not require a version.

Example fix

// before
} else if (mode === 'draft-edit') {
  if (!queryVersion) {
    throw new Error(t('agent.versionRequired'));
  }

// after - guard at navigation boundary
if (mode === 'draft-edit' && !queryVersion) {
  toast.error(t('agent.versionRequired'));
  navigate(`/agent?mode=metadata&agentName=${queryAgentName}`);
  return;
}

function canEnterDraftEdit(mode: string, agentName?: string, version?: string): boolean {
  return mode !== 'draft-edit' || (!!agentName && !!version);
}

When it happens

Trigger: Navigating to the agent editor with mode=draft-edit (or a route resolving to it) and an agentName in the query string but no `version` param. Deep-linking to a draft-edit URL without the version segment. A router state object that drops the version field.

Common situations: Bookmark or external link to the agent draft-edit page missing the version query param. Programmatic navigation that sets agentName but forgets version. URL rewrite/proxy stripping query params.

Related errors

• Agent directory metadata is only allowed when creating the f
• Agent direct-online request must contain callInterfaces
• Online Agent Version must contain callInterfaces
• Agent Version namespaceId does not match request
• Agent Version agentName does not match request

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