alibaba/nacos · error · IllegalArgumentException

Invalid Agent Version contentDigest

Error message

Invalid Agent Version contentDigest

What it means

The contentDigest field is null or does not match sha256:[0-9a-f]{64}: exactly the prefix 'sha256:' followed by 64 lowercase hexadecimal digits. Any deviation (uppercase hex, wrong length, missing prefix, different algorithm) is rejected.

Source

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

     *
     * @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) {
            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);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Compute the digest via AgentVersionContentSerializer.digest(bytes), which produces the correct sha256:<64 lowercase hex> format
2. Ensure lowercase hex and exactly 64 digits after the prefix
3. Never hand-type the digest; always derive it from the serialized content bytes

Example fix

// before
descriptor.setContentDigest("sha256:ABCDEF...");
// after
descriptor.setContentDigest(AgentVersionContentSerializer.digest(contentBytes));

private static final Pattern DIGEST = Pattern.compile("sha256:[0-9a-f]{64}");
String digest = descriptor.getContentDigest();
if (digest == null || !DIGEST.matcher(digest).matches()) {
    throw new IllegalArgumentException("contentDigest must be sha256:<64 lowercase hex>");
}

When it happens

Trigger: validate()/serialize() on a descriptor whose digest is null, uses uppercase hex (sha256:ABCDEF...), has fewer/more than 64 digits, lacks the sha256: prefix, or names a different hash. Fires on corrupted rows too.

Common situations: Digest computed with uppercase hex output; a truncated or wrong-length hash; a different algorithm (md5/sha1); a manually typed digest.

Related errors

• Agent Version storage descriptor JSON must not be empty
• Agent Version storage descriptor must be a JSON object
• Unknown Agent Version storage descriptor field: {fieldName}
• Agent Version storage descriptor must not be null
• Invalid Agent Version storage provider

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