alibaba/nacos · error · IllegalArgumentException

Unknown theme

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.

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
• 101
• 100
• 10000
• 10000

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

Appendix: 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)