{"record":{"id":"a3b913c91432a61e","repo":"alibaba/nacos","slug":"nacos-config-keyformat-must-be-nacos-config-key-f","errorCode":null,"errorMessage":"nacos_config keyFormat must be {NACOS_CONFIG_KEY_FORMAT}","messagePattern":"nacos_config keyFormat must be (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java","lineNumber":183,"sourceCode":"            || !DIGEST_PATTERN.matcher(descriptor.getContentDigest()).matches()) {\n            throw new IllegalArgumentException(\"Invalid Agent Version contentDigest\");\n        }\n        if (!AGENT_VERSION_MEDIA_TYPE.equals(descriptor.getMediaType())) {\n            throw new IllegalArgumentException(\"Agent Version mediaType must be \"\n                + AGENT_VERSION_MEDIA_TYPE);\n        }\n        if (!Integer.valueOf(SCHEMA_VERSION).equals(descriptor.getSchemaVersion())) {\n            throw new IllegalArgumentException(\"Agent Version storage schemaVersion must be \"\n                + SCHEMA_VERSION);\n        }\n        Long size = descriptor.getSize();\n        if (size == null || size < 0 || size > MAX_CONTENT_SIZE) {\n            throw new IllegalArgumentException(\n                \"Agent Version storage size must be between 0 and \" + MAX_CONTENT_SIZE);\n        }\n        if (NACOS_CONFIG_PROVIDER.equals(provider)) {\n            if (!NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {\n                throw new IllegalArgumentException(\"nacos_config keyFormat must be \"\n                    + NACOS_CONFIG_KEY_FORMAT);\n            }\n            if (!RAD_ASCII_AGENT_NAME_CODEC.equals(descriptor.getAgentNameCodec())) {\n                throw new IllegalArgumentException(\"nacos_config agentNameCodec must be \"\n                    + RAD_ASCII_AGENT_NAME_CODEC);\n            }\n        }\n    }\n    \n    private static void validateRequiredText(String field, String value, int maxLength) {\n        if (value == null || value.isEmpty() || value.length() > maxLength) {\n            throw new IllegalArgumentException(\"Invalid Agent Version storage \" + field);\n        }\n    }\n    \n    private static void validateOptionalText(String field, String value, int maxLength) {\n        if (value != null) {\n            validateRequiredText(field, value, maxLength);","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java#L165-L201","documentation":"When the provider is 'nacos_config', the keyFormat must equal exactly 'agent-version-config-v1' (AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT). This enforces the built-in nacos_config provider's storage contract; a wrong/null keyFormat means the content key layout is unspecified.","triggerScenarios":"validate()/serialize() on a descriptor with provider 'nacos_config' but keyFormat null, empty, or any value other than 'agent-version-config-v1'. Fires on a corrupted/custom-edited row too.","commonSituations":"Switching the provider field to nacos_config without setting keyFormat; a manual edit; a stale descriptor from before the contract was enforced.","solutions":["Set keyFormat to AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT when provider is nacos_config","Use AgentVersionStorageService.buildDescriptor, which sets keyFormat correctly for the nacos_config provider","Re-publish the version"],"exampleFix":"// before\ndescriptor.setProvider(\"nacos_config\");\ndescriptor.setKeyFormat(null);\n// after\ndescriptor.setProvider(\"nacos_config\");\ndescriptor.setKeyFormat(AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT);","handlingStrategy":"validation","validationCode":"if (AgentVersionStorageDescriptorSerializer.NACOS_CONFIG_PROVIDER.equals(provider)\n        && !AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {\n    descriptor.setKeyFormat(AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use AgentVersionStorageService.buildDescriptor for the nacos_config provider; it sets keyFormat correctly","When changing provider, also update the provider-specific fields"],"tags":["java","nacos","ai-agent","validation","provider-contract","storage-descriptor"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}