flowable/flowable-engine · error · FlowableException

In order to use comments, history should be enabled

Error message

In order to use comments, history should be enabled

What it means

Comments (and events) are persisted through the history subsystem in Flowable. CommentEntityManagerImpl.checkHistoryEnabled() throws this FlowableException when any comment insert/update or comment/event query runs while history is disabled.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/persistence/entity/CommentEntityManagerImpl.java:192

            // Forced to fetch the process-instance to associate the right
            // process definition
            String processDefinitionId = null;
            String processInstanceId = comment.getProcessInstanceId();
            if (comment.getProcessInstanceId() != null) {
                ExecutionEntity process = getExecutionEntityManager().findById(comment.getProcessInstanceId());
                if (process != null) {
                    processDefinitionId = process.getProcessDefinitionId();
                }
            }
            getEventDispatcher().dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_DELETED, 
                    commentEntity, processInstanceId, processInstanceId, processDefinitionId),
                    engineConfiguration.getEngineCfgKey());
        }
    }

    protected void checkHistoryEnabled() {
        if (!getHistoryManager().isHistoryEnabled()) {
            throw new FlowableException("In order to use comments, history should be enabled");
        }
    }

    protected ExecutionEntityManager getExecutionEntityManager() {
        return engineConfiguration.getExecutionEntityManager();
    }

    protected HistoryManager getHistoryManager() {
        return engineConfiguration.getHistoryManager();
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Enable history in the engine configuration (setHistoryLevel(HistoryLevel.ACTIVITY) or higher, or flowable.history-level=activity in config).
2. Ensure the history tables (ACT_HI_*) exist by running the engine's schema update after enabling history.
3. If history must stay disabled, remove/feature-flag all comment usage — comments are unsupported without history.

Example fix

// before
ProcessEngineConfiguration cfg = ...;
cfg.setHistoryLevel(HistoryLevel.NONE);
taskService.addComment(taskId, processInstanceId, "note"); // throws
// after
ProcessEngineConfiguration cfg = ...;
cfg.setHistoryLevel(HistoryLevel.AUDIT);
taskService.addComment(taskId, processInstanceId, "note");

// Java: guard comment APIs
if (!processEngine.getProcessEngineConfiguration().getHistoryManager().isHistoryEnabled()) {
    throw new IllegalStateException("Comments require history to be enabled");
}

try {
    taskService.addComment(taskId, processInstanceId, message);
} catch (FlowableException e) {
    if (e.getMessage().contains("history should be enabled")) {
        // enable history or route comments to an alternate store
    } else { throw e; }
}

When it happens

Trigger: Calling TaskService.addComment, updating a comment, findCommentsByTaskId, findCommentsByTaskIdAndType, findCommentsByType, or findEventsByTaskId while the engine history level is NONE.

Common situations: Engine configured with history=none for throughput; comment code added to an existing app that was configured without history; test environment config differing from production where history is on.

Related errors

• In order to use attachments, history should be enabled
• In order to use comments, history should be enabled
• no org.flowable.app.engine.AppEngine defined in the applicat
• transactionManager is required property for SpringAppEngineC
• Could not find an implementation of the org.flowable.cdi.spi

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/b69e76123fb82250. Report an issue: GitHub.