flowable/flowable-engine · error · ActivitiException

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

Error message

It is not allowed to add an attachment to a suspended process instance

What it means

The command refuses to attach content to a suspended process instance, throwing ActivitiException. Like suspended tasks, suspended executions are frozen: state-mutating related operations such as attachments are disallowed.

Solutions

1. Activate the process instance first (runtimeService.activateProcessInstanceById)
2. Check the suspension state before attaching and queue the operation
3. Attach the document to a task in a non-suspended instance instead

Example fix

// before
taskService.createAttachment("text", null, procInstId, "n", "d", stream);
// after
ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(procInstId).singleResult();
if (pi != null && !pi.isSuspended()) {
    taskService.createAttachment("text", null, procInstId, "n", "d", stream);
}

ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(procInstId).singleResult();
boolean allowed = pi != null && !pi.isSuspended();

boolean canAttachToInstance(ProcessInstance pi) { return pi != null && !pi.isSuspended(); }

try { taskService.createAttachment(...); } catch (ActivitiException e) { if (e.getMessage().contains("suspended")) { /* defer until activated */ } }

When it happens

Trigger: createAttachment with a processInstanceId whose execution.isSuspended() is true, typically after suspendProcessInstanceById/ByProcessDefinitionId.

Common situations: Bulk suspend for maintenance or migration while document workflows keep running; an instance suspended by policy awaiting approval.

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 task
• Cannot add a comment to a suspended
• It is not allowed to add an attachment to a suspended
• Process instance doesn't exist
• Process instance doesn't exist

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

Appendix: source

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

            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)