{"record":{"id":"5b6136697939731d","repo":"alibaba/nacos","slug":"scope-must-be-public-or-private","errorCode":null,"errorMessage":"scope must be PUBLIC or PRIVATE","messagePattern":"scope must be PUBLIC or PRIVATE","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java","lineNumber":337,"sourceCode":"        validateVersionInfoCatalogConsistency(versionInfo, versionCatalog);\n        validateEpochMillis(metaVersion, \"metaVersion\");\n        validateEpochMillis(createTime, \"createTime\");\n        validateEpochMillis(updateTime, \"updateTime\");\n    }\n    \n    private static void validateProvider(AgentProvider provider) {\n        if (provider == null) {\n            return;\n        }\n        validateRequiredLength(provider.getName(), MAX_PROVIDER_NAME_LENGTH, \"provider.name\");\n        if (provider.getUrl() != null) {\n            validateAbsoluteUri(provider.getUrl(), \"provider.url\");\n        }\n    }\n    \n    private static void validateScope(String scope) {\n        if (!\"PUBLIC\".equals(scope) && !\"PRIVATE\".equals(scope)) {\n            throw new IllegalArgumentException(\"scope must be PUBLIC or PRIVATE\");\n        }\n    }\n    \n    private static void validateResourceStatus(String status) {\n        if (!AiConstants.Agent.RESOURCE_STATUS_ENABLE.equals(status)\n            && !AiConstants.Agent.RESOURCE_STATUS_DISABLE.equals(status)) {\n            throw new IllegalArgumentException(\"Invalid Agent resource status: \" + status);\n        }\n    }\n    \n    private static void validateVersionStatus(String status) {\n        if (!AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(status)\n            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {\n            throw new IllegalArgumentException(\"Invalid Agent Version status: \" + status);\n        }","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/api/src/main/java/com/alibaba/nacos/api/ai/utils/AgentModelValidator.java#L319-L355","documentation":"Thrown by the private validateScope as an IllegalArgumentException when the agent's scope field is not exactly \"PUBLIC\" or \"PRIVATE\". Scope controls visibility of the agent resource across the namespace and is a required, enumerated field.","triggerScenarios":"Calling validateAgent or validateAgentSummary (which call validateScope internally) when agent.getScope() is null, empty, or any value other than \"PUBLIC\"/\"PRIVATE\" (e.g. \"public\", \"Shared\", \"ORG\").","commonSituations":"The scope was omitted (null) in a create/update payload; a client sent lowercase \"public\" instead of uppercase; a new scope concept was introduced but not yet supported by this validator version.","solutions":["Set scope to exactly \"PUBLIC\" or \"PRIVATE\" (uppercase) when creating or updating the agent.","Use the AiConstants scope constant if one exists, or centralize the allowed values.","Validate scope at the API boundary and reject/normalize before reaching the model validator."],"exampleFix":"// before\nagent.setScope(\"public\"); // wrong case\nAgentModelValidator.validateAgent(agent); // throws\n\n// after\nagent.setScope(\"PUBLIC\");\n// or\nagent.setScope(\"PRIVATE\");\nAgentModelValidator.validateAgent(agent); // ok","handlingStrategy":"validation","validationCode":"static final Set<String> SCOPES = Set.of(\"PUBLIC\", \"PRIVATE\");\nif (!SCOPES.contains(agent.getScope())) {\n    agent.setScope(\"PRIVATE\"); // safe default\n}\nAgentModelValidator.validateAgent(agent);","typeGuard":"static boolean isValidScope(String scope) {\n    return \"PUBLIC\".equals(scope) || \"PRIVATE\".equals(scope);\n}","tryCatchPattern":null,"preventionTips":["Use uppercase \"PUBLIC\"/\"PRIVATE\" exactly; do not rely on case-insensitivity.","Centralize allowed scope values in a constant set and validate at the API boundary.","Default new agents to a defined scope rather than null."],"tags":["java","nacos","ai","agents","validation","enum"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}