flowable/flowable-engine · error · ActivitiException

In order to use attachments, history should be enabled

Error message

In order to use attachments, history should be enabled

What it means

ActivitiException thrown by AttachmentEntityManager.checkHistoryEnabled when an attachment operation is performed while history is disabled. Attachments are stored as history entities, so with history level 'none' the engine refuses the operation rather than silently losing data. It is a guard enforcing that the history subsystem is available before touching attachments.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/persistence/entity/AttachmentEntityManager.java:80

        for (AttachmentEntity attachment : attachments) {
            String contentId = attachment.getContentId();
            if (contentId != null) {
                getByteArrayManager().deleteByteArrayById(contentId);
            }
            getDbSqlSession().delete(attachment);
            if (dispatchEvents) {
                getProcessEngineConfiguration().getEventDispatcher().dispatchEvent(
                        ActivitiEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_DELETED, 
                                attachment, executionId, processInstanceId, processDefinitionId),
                        EngineConfigurationConstants.KEY_PROCESS_ENGINE_CONFIG);
            }
        }
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set history to at least 'activity' (e.g., process.engine.history=activity or HistoryLevel.ACTIVITY) in the engine configuration
2. If history must stay off, stop using attachments and store related documents in your own storage keyed by task/process id
3. Check getHistoryManager().isHistoryEnabled() before invoking attachment APIs
4. Wrap attachment calls in try-catch for ActivitiException with a graceful fallback

Example fix

// before (flowable.cfg.xml)
<property name="history" value="none"/>
// after
<property name="history" value="activity"/>

if (!processEngine.getProcessEngineConfiguration().getHistoryManager().isHistoryEnabled()) {
    throw new IllegalStateException("Attachments require history to be enabled");
}

try {
    taskService.createAttachment(...);
} catch (ActivitiException e) {
    if (e.getMessage().contains("history should be enabled")) {
        // fallback: store attachment in external storage
    } else throw e;
}

When it happens

Trigger: Calling TaskService.createAttachment(...) / getProcessInstanceAttachments / getTaskAttachments, or deleteAttachmentsByTaskId, when the engine is configured with history level none (historyManager.isHistoryEnabled() returns false).

Common situations: Engine configured with process.engine.history=none for performance, then code paths using attachments are exercised; production config hardened without auditing which APIs require history.

Related errors

• In order to use attachments, history should be enabled
• In order to use comments, history should be enabled
• Setting a deployment name is not supported for apps
• CommandInvoker must be the last interceptor in the chain
• In order to use comments, history should be enabled

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