flowable/flowable-engine · error · FlowableException

It is not allowed to add an attachment to a suspended

Error message

It is not allowed to add an attachment to a suspended 

What it means

CreateAttachmentCmd refuses to add an attachment to a suspended task. While the task's process/case is suspended, mutating operations such as adding attachments are disallowed. A plain FlowableException with the task's toString is thrown.

Solutions

1. Resume the suspended instance first: runtimeService.activateProcessInstanceById(instanceId) (or activate the task), then add the attachment.
2. Check suspension state before uploading: if the task is suspended, queue the attachment or inform the user.
3. Remove the suspension if it was set accidentally (e.g. leftover suspension policy in config).

Example fix

// before
taskService.createAttachment(null, taskId, null, name, desc, url);
// after
Task task = taskService.createTaskQuery().taskId(taskId).singleResult();
if (task.isSuspended()) {
    runtimeService.activateProcessInstanceById(task.getProcessInstanceId());
}
taskService.createAttachment(null, taskId, task.getProcessInstanceId(), name, desc, url);

Task task = taskService.createTaskQuery().taskId(taskId).singleResult();
if (task != null && task.isSuspended()) {
    throw new IllegalStateException("Task " + taskId + " is suspended");
}

try {
    taskService.createAttachment(null, taskId, pid, name, desc, url);
} catch (FlowableException e) {
    if (e.getMessage().contains("suspended")) { queueForLater(taskId, url); } else { throw e; }
}

When it happens

Trigger: Calling TaskService.createAttachment on a task whose containing process instance (or standalone task) is in suspended state, i.e. task.isSuspended() is true.

Common situations: Suspended process instances during maintenance windows or after runtimeService.suspendProcessInstanceById(...); users uploading documents while the case is frozen for review; batch importers that suspend instances and still write attachments.

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

• Cannot add a comment to a suspended
• Cannot add a comment to a suspended
• Cannot complete case task. Parent process instance
• Cannot complete process instance. Parent process instance
• Cannot find task with id

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/CreateAttachmentCmd.java:147

            eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_CREATED, attachment, 
                    processInstanceId, processInstanceId, processDefinitionId), processEngineConfiguration.getEngineCfgKey());
            eventDispatcher.dispatchEvent(FlowableEventBuilder.createEntityEvent(FlowableEngineEventType.ENTITY_INITIALIZED, attachment, 
                    processInstanceId, processInstanceId, processDefinitionId), processEngineConfiguration.getEngineCfgKey());
        }

        return attachment;
    }

    protected TaskEntity verifyTaskParameters(CommandContext commandContext) {
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        TaskEntity task = processEngineConfiguration.getTaskServiceConfiguration().getTaskService().getTask(taskId);

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

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

        return task;
    }

    protected ExecutionEntity verifyExecutionParameters(CommandContext commandContext) {
        ExecutionEntity execution = CommandContextUtil.getExecutionEntityManager(commandContext).findById(processInstanceId);

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

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

        return execution;
    }

View on GitHub (pinned to d6d39ce1c6)