What causes "Invalid Agent Version storage provider" in alibaba/nacos?

Set provider to a valid identifier; the built-in default is 'nacos_config'

alibaba/nacos · error · IllegalArgumentException

Invalid Agent Version storage provider

Error message

Invalid Agent Version storage provider

What it means

The provider field is null, longer than 64 characters, or fails the pattern [A-Za-z0-9][A-Za-z0-9_-]{0,63}: it must start with an alphanumeric character and contain only letters, digits, underscore, or hyphen, total length 1-64.

Source

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

        validateJsonText(root, "mediaType", false);
        validateJsonInteger(root, "schemaVersion");
        validateJsonInteger(root, "size");
    }
    
    /**
     * Validate an Agent Version storage descriptor against the internal storage schema.
     *
     * @param descriptor storage descriptor
     * @throws IllegalArgumentException when the descriptor is invalid
     */
    public static void validate(AgentVersionStorageDescriptor descriptor) {
        if (descriptor == null) {
            throw new IllegalArgumentException("Agent Version storage descriptor must not be null");
        }
        String provider = descriptor.getProvider();
        if (provider == null || provider.length() > MAX_PROVIDER_LENGTH
            || !PROVIDER_PATTERN.matcher(provider).matches()) {
            throw new IllegalArgumentException("Invalid Agent Version storage provider");
        }
        validateRequiredText("key", descriptor.getKey(), MAX_KEY_LENGTH);
        validateOptionalText("keyFormat", descriptor.getKeyFormat(), MAX_FORMAT_LENGTH);
        validateOptionalText("agentNameCodec", descriptor.getAgentNameCodec(), MAX_FORMAT_LENGTH);
        if (descriptor.getContentDigest() == null
            || !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) {

View on GitHub (pinned to 9b989acdf1)

Solutions

Set provider to a valid identifier; the built-in default is 'nacos_config'
Ensure it starts with a letter or digit and uses only [A-Za-z0-9_-]
Keep the length between 1 and 64 characters

Example fix

// before
descriptor.setProvider("object.store");
// after
descriptor.setProvider("object_store");

Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern PROVIDER = Pattern.compile("[A-Za-z0-9][A-Za-z0-9_-]{0,63}");
String provider = descriptor.getProvider();
if (provider == null || !PROVIDER.matcher(provider).matches()) {
    throw new IllegalArgumentException("provider must match [A-Za-z0-9][A-Za-z0-9_-]{0,63}");
}

Prevention

Use the NACOS_CONFIG_PROVIDER constant for the built-in provider
For custom providers, validate the name against the pattern before constructing the descriptor

When it happens

Trigger: validate()/serialize() on a descriptor whose provider is null, empty, starts with a non-alphanumeric ("-provider"), contains a dot ("a.b"), or exceeds 64 chars. Also fires on a corrupted storage row.

Common situations: A custom storage-provider name containing a dot or space; provider left unset; a hand-edited column with an invalid identifier.

Related errors

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