Activiti/Activiti · error · ActivitiIllegalArgumentException

Illegal value for history-level:

Error message

Illegal value for history-level: 

What it means

Thrown by HistoryLevel.getHistoryLevelForKey when the configured history-level string does not match any known level key (none, activity, audit, full), so engine configuration cannot resolve a history level. The offending key is appended to the message.

Solutions

1. Use one of: none, activity, audit, full (exact lowercase keys).
2. Check the value injected for processEngineConfiguration.setHistory / historyLevel property.
3. If reading from config files/env, log and normalize the value (trim, lowercase) before passing.
4. Consider using HistoryLevel enum directly instead of string keys to fail at compile time.

Example fix

// before
config.setHistory("Auditing");
// after
config.setHistory("audit"); // one of none|activity|audit|full

List<String> valid = Arrays.asList("none","activity","audit","full");
if (!valid.contains(historyLevel)) throw new IllegalArgumentException("illegal history-level: " + historyLevel);

try { config.setHistory(rawLevel); } catch (ActivitiIllegalArgumentException e) { config.setHistory("audit"); }

When it happens

Trigger: Passing a history-level string via processEngineConfiguration.setHistory(...) or the activiti.properties/Spring config that is not one of the supported keys.

Common situations: Typos like 'Audit' (case-sensitive) or 'auditing'; copying config from other engines (e.g. Flowable/CRM history levels); environment variables injecting wrong values.

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

• businessCalendars can not be null
• Can't find scripting engine for
• Cannot set JPA variable
• couldn't deduct database vendor from database product name…
• couldn't lookup datasource from :

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/363997eec5bc9dcc. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/history/HistoryLevel.java:51

    private HistoryLevel(String key) {
        this.key = key;
    }

    /**
     * @param key
     *          string representation of level
     * @return {@link HistoryLevel} for the given key
     * @throws ActivitiException
     *           when passed in key doesn't correspond to existing level
     */
    public static HistoryLevel getHistoryLevelForKey(String key) {
        for (HistoryLevel level : values()) {
            if (level.key.equals(key)) {
                return level;
            }
        }
        throw new ActivitiIllegalArgumentException("Illegal value for history-level: " + key);
    }

    /**
     * String representation of this history-level.
     */
    public String getKey() {
        return key;
    }

    /**
     * Checks if the given level is the same as, or higher in order than the level this method is executed on.
     */
    public boolean isAtLeast(HistoryLevel level) {
        // Comparing enums actually compares the location of values declared in
        // the enum
        return this.compareTo(level) >= 0;
    }
}

View on GitHub (pinned to 56435b1a97)