alibaba/nacos · error · IllegalArgumentException

Physical key prefix leaves insufficient room for a SHA-256 d

Error message

Physical key prefix leaves insufficient room for a SHA-256 digest

What it means

NacosAiConfigKeyCodec.fitToLength tried to apply the SHA-256 length-fallback (prefix + 'sha256.' + 64-char digest) but the result still exceeds maxLength. This means the preserved prefix is so long that even a 64-character hash cannot fit within the Nacos Config dataId limit.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/NacosAiConfigKeyCodec.java:220

        }
        return out;
    }
    
    private static boolean hasReservedEncodedPrefix(String value) {
        return value.regionMatches(true, 0, ENCODED_PREFIX, 0, ENCODED_PREFIX.length());
    }
    
    private static String fitToLength(String candidate, int maxLength, String preservedPrefix) {
        if (candidate == null) {
            return null;
        }
        String prefix = preservedPrefix == null ? "" : preservedPrefix;
        if (candidate.length() <= maxLength && !isHashedPhysicalKey(candidate, prefix)) {
            return candidate;
        }
        String result = prefix + HASHED_PREFIX + sha256Hex(candidate);
        if (result.length() > maxLength) {
            throw new IllegalArgumentException(
                "Physical key prefix leaves insufficient room for a SHA-256 digest");
        }
        return result;
    }
    
    private static boolean isHashedPhysicalKey(String candidate, String preservedPrefix) {
        if (candidate == null) {
            return false;
        }
        String marker = (preservedPrefix == null ? "" : preservedPrefix) + HASHED_PREFIX;
        if (candidate.length() != marker.length() + 64
            || !candidate.regionMatches(true, 0, marker, 0, marker.length())) {
            return false;
        }
        for (int i = marker.length(); i < candidate.length(); i++) {
            if (Character.digit(candidate.charAt(i), 16) < 0) {
                return false;
            }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Shorten the preservedPrefix or reduce the number of concatenated segments.
2. Hash more of the key (including part of the prefix) rather than preserving the full prefix in plaintext.
3. Increase maxLength if the storage backend supports a larger dataId (but 255 is the Nacos Config ceiling).
4. Redesign the key layout to use fewer characters for static prefix portions.

Example fix

// before
String prefix = "ai_registry__production__my-very-long-tenant-identifier__";
// prefix + 'sha256.' + 64 chars > maxLength

// after -- hash the tenant portion too
String prefix = "ai_registry__prod__";
// now prefix + sha256 digest fits within 255

// Before calling fitToLength indirectly via build*Group, check prefix length
int digestBudget = prefix.length() + NacosAiConfigKeyCodec.HASHED_PREFIX.length() + 64;
if (digestBudget > NacosAiConfigKeyCodec.MAX_DATA_ID_LENGTH) {
    // shorten prefix or redesign key layout
    prefix = shortenPrefix(prefix);
}

public static boolean prefixFitsSha256(String prefix, int maxLength) {
    int needed = prefix.length()
        + NacosAiConfigKeyCodec.HASHED_PREFIX.length() + 64;
    return needed <= maxLength;
}

try {
    group = AgentSpecUtils.buildAgentSpecVersionGroup(name, version);
} catch (IllegalArgumentException e) {
    // prefix too long; hash more of the key or shorten the prefix
    name = hashShortName(name);
    group = AgentSpecUtils.buildAgentSpecVersionGroup(name, version);
}

When it happens

Trigger: A physical key prefix (e.g. a long namespace or resource-type prefix) combined with the sha256 fallback exceeds MAX_DATA_ID_LENGTH (255) or the provided maxLength. Typically caused by deeply nested or overly verbose prefix construction.

Common situations: Custom namespace hierarchies or multi-tenant prefixes that are very long. Group/dataId templates that concatenate many segments. A change to the prefix scheme increased its length beyond the digest budget.

Related errors

• empty payload after enc.
• illegal hex length: {len}
• illegal hex at index {i}
• Unable to serialize AgentVersionContent
• AgentVersionContent exceeds {MAX_CONTENT_SIZE} bytes

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