{"record":{"id":"1e433adb80a824a8","repo":"flowable/flowable-engine","slug":"cannot-execute-operation-because-process-definitio-1e433a","errorCode":null,"errorMessage":"Cannot execute operation because process definition '\" + processDefinition.getName() + \"' (id=\" + processDefinition.getId() + \") is suspended","messagePattern":"Cannot execute operation because process definition '\" \\+ processDefinition\\.getName\\(\\) \\+ \"' \\(id=\" \\+ processDefinition\\.getId\\(\\) \\+ \"\\) is suspended","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/NeedsActiveProcessDefinitionCmd.java","lineNumber":42,"sourceCode":" * @author Joram Barrez\n */\npublic abstract class NeedsActiveProcessDefinitionCmd<T> implements Command<T>, Serializable {\n\n    private static final long serialVersionUID = 1L;\n\n    protected String processDefinitionId;\n\n    public NeedsActiveProcessDefinitionCmd(String processDefinitionId) {\n        this.processDefinitionId = processDefinitionId;\n    }\n\n    @Override\n    public T execute(CommandContext commandContext) {\n        DeploymentManager deploymentManager = commandContext.getProcessEngineConfiguration().getDeploymentManager();\n        ProcessDefinition processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);\n\n        if (deploymentManager.isProcessDefinitionSuspended(processDefinitionId)) {\n            throw new ActivitiException(\"Cannot execute operation because process definition '\"\n                    + processDefinition.getName() + \"' (id=\" + processDefinition.getId() + \") is suspended\");\n        }\n\n        return execute(commandContext, processDefinition);\n    }\n\n    /**\n     * Subclasses should implement this. The provided {@link ProcessDefinition} is guaranteed to be an active process definition (ie. not suspended).\n     */\n    protected abstract T execute(CommandContext commandContext, ProcessDefinition processDefinition);\n\n}\n","sourceCodeStart":24,"sourceCodeEnd":55,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/NeedsActiveProcessDefinitionCmd.java#L24-L55","documentation":"Thrown by NeedsActiveProcessDefinitionCmd.execute() when the target process definition is suspended. The command resolves the deployed definition via the DeploymentManager and refuses to proceed while isProcessDefinitionSuspended returns true, raising an ActivitiException naming the definition and its id. New operations against that definition version are blocked until it is activated.","triggerScenarios":"Starting a process instance (e.g. runtimeService.startProcessInstanceById/ByKey pinned to a version) or any command extending NeedsActiveProcessDefinitionCmd while the definition was suspended through repositoryService.suspendProcessDefinitionById/ByKey (including suspendProcessInstances flag).","commonSituations":"Ops teams suspend a definition during a migration or bugfix freeze; a form or API still points at an old suspended version; default (latest) version resolution lands on a suspended deployment.","solutions":["Re-activate the definition: repositoryService.activateProcessDefinitionById(id) or activateProcessDefinitionByKey(key).","Check suspension first: repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult().isSuspended().","Deploy or point to a newer active version instead of operating on the suspended one.","If suspension is intentional, block the user action at the application layer before invoking the engine."],"exampleFix":"// before\nruntimeService.startProcessInstanceById(processDefinitionId);\n\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionId(processDefinitionId).singleResult();\nif (pd.isSuspended()) {\n    repositoryService.activateProcessDefinitionById(pd.getId());\n}\nruntimeService.startProcessInstanceById(processDefinitionId);","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult();\nif (pd != null && pd.isSuspended()) throw new IllegalStateException(\"definition suspended: \" + id);","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.startProcessInstanceById(id);\n} catch (ActivitiException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"is suspended\")) {\n        repositoryService.activateProcessDefinitionById(id);\n    }\n}","preventionTips":["Prefer startProcessInstanceByKey with the latest active version rather than pinned suspended ids","After deployments/migrations, verify definitions are active before enabling start endpoints","Document suspension windows to app teams"],"tags":["activiti","flowable","suspended-definition","state"],"backgroundTag":"invalid-state-transition","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}