alibaba/nacos · error · IllegalArgumentException

Unknown theme: {value}

Error message

Unknown theme: {value}

What it means

Icon.Theme.fromValue (a Jackson @JsonCreator) throws IllegalArgumentException when the input does not case-insensitively match 'light' or 'dark'. This fires during JSON deserialization of an Icon object whose theme field has an unrecognized value.

Source

Thrown at api/src/main/java/com/alibaba/nacos/api/ai/model/mcp/registry/Icon.java:237

        @JsonValue
        public String getValue() {
            return value;
        }
        
        /**
         * Create from value.
         *
         * @param value value
         * @return Theme
         */
        @JsonCreator
        public static Theme fromValue(String value) {
            for (Theme t : Theme.values()) {
                if (t.value.equalsIgnoreCase(value)) {
                    return t;
                }
            }
            throw new IllegalArgumentException("Unknown theme: " + value);
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Normalize the theme value to 'light' or 'dark' before building or sending the Icon.
2. If the source cannot be controlled, pre-process the JSON or use a custom Jackson deserializer that defaults unknown themes to 'light'.
3. Validate the theme field at the API boundary.

Example fix

// before
{ "src": "icon.png", "mimeType": "image/png", "theme": "auto" } // throws

// after
{ "src": "icon.png", "mimeType": "image/png", "theme": "light" } // ok

// Pre-process:
String theme = Set.of("light","dark").contains(rawTheme.toLowerCase())
    ? rawTheme.toLowerCase() : "light";

private static final Set<String> VALID_THEMES = Set.of("light", "dark");

String normalized = rawTheme == null ? null : rawTheme.trim().toLowerCase();
if (!VALID_THEMES.contains(normalized)) {
    normalized = "light"; // or reject
}

public static boolean isValidTheme(String value) {
    if (value == null) return false;
    String v = value.trim().toLowerCase();
    return "light".equals(v) || "dark".equals(v);
}

try {
    Icon icon = objectMapper.readValue(json, Icon.class);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unknown theme")) {
        // default to 'light' and retry
    }
    throw e;
}

When it happens

Trigger: Deserializing JSON with a theme value like 'Light', 'DARK', 'medium', 'auto', 'system', or any string other than the two allowed values. While case-insensitive matching covers 'LIGHT' and 'Dark', anything else fails.

Common situations: A third-party system sends a theme value outside the spec. A UI component defaults to 'auto' or 'system'. A locale or locale-influenced serialization produced an unexpected value.

Related errors

• Unknown mimeType: {value}
• 101
• 10000
• 10000
• 10000

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