{"record":{"id":"5e4dffbbdd892da8","repo":"alibaba/nacos","slug":"agent-versionrequired","errorCode":null,"errorMessage":"agent.versionRequired","messagePattern":"agent\\.versionRequired","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"console-ui-next/src/pages/newAgent/index.tsx","lineNumber":189,"sourceCode":"        return;\n      }\n      if (!queryAgentName) {\n        toast.error(t('agent.nameRequired'));\n        setLoading(false);\n        return;\n      }\n      try {\n        if (mode === 'metadata') {\n          const response = await agentApi.getAgent({\n            namespaceId,\n            agentName: queryAgentName,\n          });\n          if (active) {\n            setValues(metadataToEditorValues(response.data.agent));\n          }\n        } else if (mode === 'draft-edit') {\n          if (!queryVersion) {\n            throw new Error(t('agent.versionRequired'));\n          }\n          const response = await agentApi.getVersion({\n            namespaceId,\n            agentName: queryAgentName,\n            version: queryVersion,\n          });\n          if (active) {\n            setValues((current) => ({\n              ...current,\n              agentName: queryAgentName,\n              version: queryVersion,\n              ...callInterfacesToEditorValues(response.data.callInterfaces),\n              changeDescription: response.data.changeDescription || '',\n            }));\n          }\n        }\n      } catch (error) {\n        toast.error(error instanceof Error ? error.message : t('agent.loadFailed'));","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/console-ui-next/src/pages/newAgent/index.tsx#L171-L207","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Include the `version` query parameter when navigating to draft-edit mode (e.g. ?mode=draft-edit&agentName=X&version=1.0.0).","Add a route guard that redirects away from draft-edit when version is missing, instead of letting the effect throw.","If versionless editing is intended, switch to mode=metadata which does not require a version."],"exampleFix":"// before\n} else if (mode === 'draft-edit') {\n  if (!queryVersion) {\n    throw new Error(t('agent.versionRequired'));\n  }\n\n// after - guard at navigation boundary\nif (mode === 'draft-edit' && !queryVersion) {\n  toast.error(t('agent.versionRequired'));\n  navigate(`/agent?mode=metadata&agentName=${queryAgentName}`);\n  return;\n}","handlingStrategy":"validation","validationCode":"function canEnterDraftEdit(mode: string, agentName?: string, version?: string): boolean {\n  return mode !== 'draft-edit' || (!!agentName && !!version);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include the version query param when linking to draft-edit mode.","Add a route guard that redirects when version is missing.","Use mode=metadata for versionless agent editing."],"tags":["agent","typescript","react","routing","validation"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}