flowable/flowable-engine · error · ActivitiException

It is not allowed to add an attachment to a suspended task

Error message

It is not allowed to add an attachment to a suspended task

What it means

Suspended-state invariant in CreateAttachmentCmd.verifyParameters: attachments cannot be added while the task's process definition is suspended; the check protects suspended deployments from modification.

Solutions

1. Resume the process instance/task (runtimeService.activateProcessInstanceById) before attaching
2. Check task.isSuspended() or the execution state before calling createAttachment
3. Redirect the attachment to a different target or queue it until the suspension is lifted

Example fix

// before
taskService.createAttachment("text", taskId, null, "n", "d", stream);
// after
Task t = taskService.createTaskQuery().taskId(taskId).singleResult();
if (t != null && !t.isSuspended()) {
    taskService.createAttachment("text", taskId, null, "n", "d", stream);
}

Task t = taskService.createTaskQuery().taskId(taskId).singleResult();
boolean allowed = t != null && !t.isSuspended();

boolean canAttach(Task t) { return t != null && !t.isSuspended(); }

try { taskService.createAttachment(...); } catch (ActivitiException e) { if (e.getMessage().contains("suspended")) { /* queue or resume first */ } }

When it happens

Trigger: Adding an attachment to a task whose process instance (or the task itself) was suspended via runtimeService.suspendProcessInstanceById / suspendProcessInstanceByProcessDefinitionId.

Common situations: An admin suspended a process definition or instance pending a fix, and users still try to enrich tasks; automated document pipelines keep posting attachments during a suspension window.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• It is not allowed to add an attachment to a suspended…
• Cannot add a comment to a suspended
• Cannot find task with id
• Cannot find task with id
• It is not allowed to add an attachment to a suspended

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/CreateAttachmentCmd.java:121

            commandContext.getProcessEngineConfiguration().getEventDispatcher().dispatchEvent(
                    ActivitiEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_INITIALIZED, 
                            attachment, processInstanceId, processInstanceId, processDefinitionId),
                    EngineConfigurationConstants.KEY_PROCESS_ENGINE_CONFIG);
        }

        return attachment;
    }

    private void verifyParameters(CommandContext commandContext) {
        if (taskId != null) {
            TaskEntity task = commandContext.getTaskEntityManager().findTaskById(taskId);

            if (task == null) {
                throw new ActivitiObjectNotFoundException("Cannot find task with id " + taskId, Task.class);
            }

            if (task.isSuspended()) {
                throw new ActivitiException("It is not allowed to add an attachment to a suspended task");
            }
        }

        if (processInstanceId != null) {
            ExecutionEntity execution = commandContext.getExecutionEntityManager().findExecutionById(processInstanceId);

            if (execution == null) {
                throw new ActivitiObjectNotFoundException("Process instance " + processInstanceId + " doesn't exist", ProcessInstance.class);
            }

            if (execution.isSuspended()) {
                throw new ActivitiException("It is not allowed to add an attachment to a suspended process instance");
            }
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)