Activiti/Activiti · 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

Activiti stores attachments as history entities, so any attachment operation requires the process engine history to be enabled. AttachmentEntityManagerImpl.checkHistoryEnabled throws this ActivitiException when isHistoryEnabled() returns false (history level 'none'). Without history there is no table where attachment rows live.

Solutions

1. Enable history: set historyLevel to at least ACTIVITY (e.g. <property name="historyLevel" value="audit"/> in activiti.cfg.xml or setHistoryLevel(HistoryLevel.ACTIVITY)).
2. Restart/rebuild the engine so the new history level applies; old engines with none need the schema intact (it is, history tables just stay unused).
3. If history must stay off, stop using attachment APIs and store attachments in your own application tables.
4. Check historyLevel programmatically: processEngineConfiguration.getHistoryLevel() before calling attachment APIs.

Example fix

// before (activiti.cfg.xml)
<property name="historyLevel" value="none"/>
// after
<property name="historyLevel" value="audit"/>

if (processEngineConfig.getHistoryLevel() == org.activiti.engine.impl.history.HistoryLevel.NONE) {
    throw new IllegalStateException("Attachments require history to be enabled");
}

try {
    taskService.createAttachment(type, taskId, procInstId, name, desc, content);
} catch (org.activiti.engine.ActivitiException e) {
    if (e.getMessage().contains("history should be enabled")) {
        throw new MisconfiguredEngineException("Enable history to use attachments", e);
    }
    throw e;
}

When it happens

Trigger: Calling TaskService.createAttachment(...), taskService.getProcessInstanceAttachments / getTaskAttachments, or deleting attachments by task while engine config has historyLevel set to none (processEngineConfiguration.setHistoryLevel(HistoryLevel.NONE) or historyLevel none in config).

Common situations: Performance-tuned engines that disabled history, then code paths using attachments fail; environment config (prod) differing from dev where history was on; adding attachment features to an app that was configured history-free from the start.

Related errors

• In order to use comments, history should be enabled
• A numeric value between 1 and 5 must follow the '#' option
• Activiti database problem
• activity tenant id is null
• businessCalendars can not be null

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

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/persistence/entity/AttachmentEntityManagerImpl.java:111

            attachmentDataManager.delete((AttachmentEntity) attachment);

            if (dispatchEvents) {
                getEventDispatcher().dispatchEvent(
                    ActivitiEventBuilder.createEntityEvent(
                        ActivitiEventType.ENTITY_DELETED,
                        attachment,
                        executionId,
                        processInstanceId,
                        processDefinitionId
                    )
                );
            }
        }
    }

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

    public AttachmentDataManager getAttachmentDataManager() {
        return attachmentDataManager;
    }

    public void setAttachmentDataManager(AttachmentDataManager attachmentDataManager) {
        this.attachmentDataManager = attachmentDataManager;
    }
}

View on GitHub (pinned to 56435b1a97)