alibaba/nacos · error · IllegalArgumentException

20002

20002

Error message

Invalid Agent Version status: %s

What it means

Thrown by AgentValidationUtils.validateContentDigest when contentDigest is null or does not match 'sha256:' followed by exactly 64 lowercase hex digits (pattern sha256:[0-9a-f]{64}). Only lowercase hex is accepted; uppercase, a missing 'sha256:' prefix, a wrong hash length, or a different algorithm all fail.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/form/agent/admin/AgentVersionListForm.java:43

 *
 * @author Nacos
 */
public class AgentVersionListForm extends AgentAdminForm {
    
    private static final long serialVersionUID = 1L;
    
    private String status;
    
    @Override
    public void validate() throws NacosApiException {
        super.validate();
        if (StringUtils.isNotBlank(status)
            && !AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_ONLINE.equals(status)
            && !AiConstants.Agent.VERSION_STATUS_OFFLINE.equals(status)) {
            throw new IllegalArgumentException("Invalid Agent Version status: " + status);
        }
    }
    
    public String getStatus() {
        return status;
    }
    
    public void setStatus(String status) {
        this.status = status;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Compute SHA-256 and format as lowercase hex with a 'sha256:' prefix (69 chars total).
2. Use the same digest routine the server uses when materializing a Version.
3. Verify length is exactly 64 hex chars after the prefix and lowercase.

Example fix

// before
result.setContentDigest("SHA256:" + Hex.upper(sha256));
// after
result.setContentDigest("sha256:" + Hex.lower(sha256));

if (contentDigest == null
        || !contentDigest.matches("^sha256:[0-9a-f]{64}$")) {
    throw new IllegalArgumentException("Invalid contentDigest");
}

static boolean isValidContentDigest(String s) {
    return s != null && s.matches("^sha256:[0-9a-f]{64}$");
}

try {
    AgentValidationUtils.validateContentDigest(digest);
} catch (IllegalArgumentException e) {
    // return 400, field 'contentDigest'
}

When it happens

Trigger: Publishing a Version result (RadModelValidator line 283) or a revision (line 471) with a digest that is null, uses uppercase hex, a different prefix ('sha256:'), or a non-64-hex body. Common when computing a digest with a different algorithm or hex-casing.

Common situations: Hashing with SHA-512 or MD5 instead of SHA-256; uppercase hex output from a formatter; truncating or padding the hex string; forgetting to prefix with 'sha256:'.

Related errors

• 20002
• 10000
• 20002
• 10000
• 20002

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