alibaba/nacos · error · IllegalArgumentException

nacos_config keyFormat must be {NACOS_CONFIG_KEY_FORMAT}

Error message

nacos_config keyFormat must be {NACOS_CONFIG_KEY_FORMAT}

What it means

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.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/storage/AgentVersionStorageDescriptorSerializer.java:183

            || !DIGEST_PATTERN.matcher(descriptor.getContentDigest()).matches()) {
            throw new IllegalArgumentException("Invalid Agent Version contentDigest");
        }
        if (!AGENT_VERSION_MEDIA_TYPE.equals(descriptor.getMediaType())) {
            throw new IllegalArgumentException("Agent Version mediaType must be "
                + AGENT_VERSION_MEDIA_TYPE);
        }
        if (!Integer.valueOf(SCHEMA_VERSION).equals(descriptor.getSchemaVersion())) {
            throw new IllegalArgumentException("Agent Version storage schemaVersion must be "
                + SCHEMA_VERSION);
        }
        Long size = descriptor.getSize();
        if (size == null || size < 0 || size > MAX_CONTENT_SIZE) {
            throw new IllegalArgumentException(
                "Agent Version storage size must be between 0 and " + MAX_CONTENT_SIZE);
        }
        if (NACOS_CONFIG_PROVIDER.equals(provider)) {
            if (!NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {
                throw new IllegalArgumentException("nacos_config keyFormat must be "
                    + NACOS_CONFIG_KEY_FORMAT);
            }
            if (!RAD_ASCII_AGENT_NAME_CODEC.equals(descriptor.getAgentNameCodec())) {
                throw new IllegalArgumentException("nacos_config agentNameCodec must be "
                    + RAD_ASCII_AGENT_NAME_CODEC);
            }
        }
    }
    
    private static void validateRequiredText(String field, String value, int maxLength) {
        if (value == null || value.isEmpty() || value.length() > maxLength) {
            throw new IllegalArgumentException("Invalid Agent Version storage " + field);
        }
    }
    
    private static void validateOptionalText(String field, String value, int maxLength) {
        if (value != null) {
            validateRequiredText(field, value, maxLength);

View on GitHub (pinned to 9b989acdf1)

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

Example fix

// before
descriptor.setProvider("nacos_config");
descriptor.setKeyFormat(null);
// after
descriptor.setProvider("nacos_config");
descriptor.setKeyFormat(AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT);

Defensive patterns

Strategy: validation

Validate before calling

if (AgentVersionStorageDescriptorSerializer.NACOS_CONFIG_PROVIDER.equals(provider)
        && !AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT.equals(descriptor.getKeyFormat())) {
    descriptor.setKeyFormat(AgentVersionStorageDescriptor.NACOS_CONFIG_KEY_FORMAT);
}

Prevention

Use AgentVersionStorageService.buildDescriptor for the nacos_config provider; it sets keyFormat correctly
When changing provider, also update the provider-specific fields

When it happens

Trigger: 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.

Common situations: Switching the provider field to nacos_config without setting keyFormat; a manual edit; a stale descriptor from before the contract was enforced.

Related errors

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