hs-web/hsweb-framework · error · JSONException

parse enum " + type + " error, value : " + value

Error message

parse enum " + type + " error, value : " + value

What it means

EnumDict's fastjson deserializer cannot convert the incoming JSON value into an enum that implements EnumDict. It looks the value up via EnumDict.find by 'text' (or value/id) and throws JSONException when no enum constant matches.

Solutions

1. Make the enum implement EnumDict and define constants whose value/text cover all client inputs
2. Update the client payload to send a valid enum value/text
3. Add the missing dictionary item to the enum constants
4. Check the JSON structure: send {"text":"..."} or a plain value, not an arbitrary object

Example fix

// before
{"status":"已完结"}
// after
{"status":"finished"}

boolean ok = EnumDict.find(MyEnum.class, rawValue).isPresent();
if (!ok) throw new IllegalArgumentException("unknown dict value: " + rawValue);

static <E extends Enum<E> & EnumDict<?>> boolean isEnumDictValue(Class<E> type, Object v) {
    return EnumDict.find(type, v).isPresent();
}

try {
    return JSON.parseObject(text, type);
} catch (JSONException e) {
    log.warn("unparseable enum value: {}", text, e);
    return null;
}

When it happens

Trigger: Deserializing JSON into an EnumDict enum where the value (or its 'text'/'value'/'id' field) does not match any enum constant, or the target type is not actually an EnumDict enum (e.g. a plain String or Integer passed as `type`).

Common situations: Front-end sends a renamed/legacy dict label or ID; dictionary data changed in the database but enum constants were not updated; deserializing a plain enum that doesn't implement EnumDict; client sends an object without a 'text' key.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• JSON decoding error

AI-assisted analysis of hs-web/hsweb-framework@b2cfc85a57 (2026-09-13). Data as JSON: /api/errors/7ea282cbf089de89. Report an issue: GitHub.

Appendix: source

Thrown at hsweb-core/src/main/java/org/hswebframework/web/dict/EnumDict.java:371

                    if (name.length() == 0) {
                        return (T) null;
                    }
                    return (T) EnumDict.find((Class) type, name).orElse(null);
                } else if (token == JSONToken.NULL) {
                    lexer.nextToken(JSONToken.COMMA);
                    return null;
                } else {
                    value = parser.parse();
                    if (value instanceof Map) {
                        return (T) EnumDict.find(((Class) type), ((Map) value).get("value"))
                                           .orElseGet(() ->
                                                          EnumDict
                                                              .find(((Class) type), ((Map) value).get("text"))
                                                              .orElse(null));
                    }
                }

                throw new JSONException("parse enum " + type + " error, value : " + value);
            } catch (JSONException e) {
                throw e;
            } catch (Exception e) {
                throw new JSONException(e.getMessage(), e);
            }
        }

        @Override
        public int getFastMatchToken() {
            return JSONToken.LITERAL_STRING;
        }

        @Override
        @SuppressWarnings("all")
        @SneakyThrows
        public Object deserialize(JsonParser jp, DeserializationContext ctxt) throws IOException, JsonProcessingException {
            JsonNode node = jp.getCodec().readTree(jp);
            if (mapper != null) {

View on GitHub (pinned to b2cfc85a57)