flowable/flowable-engine · error · FlowableException

In order to use attachments, history should be enabled

Error message

In order to use attachments, history should be enabled

What it means

Attachment queries and task-attachment deletion require Flowable's history (activity/audit) data because attachments are stored as history entities. AttachmentEntityManagerImpl.checkHistoryEnabled() throws this FlowableException whenever the engine's history level is configured to none.

Source

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

            dataManager.delete((AttachmentEntity) attachment);

            if (dispatchEvents) {
                eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_DELETED, 
                        attachment, executionId, processInstanceId, processDefinitionId),
                        engineConfiguration.getEngineCfgKey());
            }
        }
    }
    
    @Override
    public void bulkDeleteAttachmentsByTaskId(Collection<String> taskIds) {
        dataManager.bulkDeleteAttachmentsByTaskId(taskIds);
    }

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

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

    protected ByteArrayEntityManager getByteArrayEntityManager() {
        return engineConfiguration.getByteArrayEntityManager();
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Enable history in the engine configuration, e.g. processEngineConfiguration.setHistoryLevel(HistoryLevel.ACTIVITY) (or AUDIT/FULL), or set flowable.history-level in properties.
2. If the DB schema was created with history tables absent (history none), run the schema update/creation so history tables exist after enabling history.
3. Refactor the code path to avoid attachment APIs if history must remain off (attachments are not supported without history).

Example fix

// before
ProcessEngineConfiguration cfg = ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
cfg.setHistoryLevel(HistoryLevel.NONE);
// after
ProcessEngineConfiguration cfg = ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
cfg.setHistoryLevel(HistoryLevel.AUDIT); // attachments require history

// Java: check history is enabled before using attachments
boolean historyEnabled(ProcessEngineConfigurationImpl cfg) {
    return cfg.getHistoryManager().isHistoryEnabled();
}

try {
    taskService.getProcessInstanceAttachments(processInstanceId);
} catch (FlowableException e) {
    if (e.getMessage().contains("history should be enabled")) {
        // surface config error to operator or fall back to non-history storage
    } else { throw e; }
}

When it happens

Trigger: Calling TaskService/AttachmentService APIs such as findAttachmentsByProcessInstanceId, findAttachmentsByTaskId, or deleteAttachmentsByTaskId (bulkDelete) while processEngineConfiguration history is disabled (historyLevel = none, e.g. setHistoryLevel(HistoryLevel.NONE) or history config 'none').

Common situations: Deploying Flowable with history disabled for performance, then later adding attachment features; copying an engine config from a stateless/low-footprint setup; environment-specific config where historyLevel defaults to none.

Related errors

• In order to use comments, history should be enabled
• In order to use attachments, 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/cc865cb4143abbc8. Report an issue: GitHub.