{"record":{"id":"823d3831ec2a9029","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-process-definition-823d38","errorCode":null,"errorMessage":"Cannot start process instance. Process definition <processDefinitionName> (id = <processDefinitionId>) is suspended","messagePattern":"Cannot start process instance\\. Process definition <processDefinitionName> \\(id = <processDefinitionId>\\) is suspended","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java","lineNumber":90,"sourceCode":"        }\r\n\r\n        String processDefinitionId = messageEventSubscription.getConfiguration();\r\n        if (processDefinitionId == null) {\r\n            throw new ActivitiException(\"Cannot start process instance by message: subscription to message with name '\" + messageName + \"' is not a message start event.\");\r\n        }\r\n\r\n        DeploymentManager deploymentManager = commandContext\r\n                .getProcessEngineConfiguration()\r\n                .getDeploymentManager();\r\n\r\n        ProcessDefinitionEntity processDefinition = (ProcessDefinitionEntity) deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);\r\n        if (processDefinition == null) {\r\n            throw new ActivitiObjectNotFoundException(\"No process definition found for id '\" + processDefinitionId + \"'\", ProcessDefinition.class);\r\n        }\r\n\r\n        // Do not start process a process instance if the process definition is suspended\r\n        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {\r\n            throw new ActivitiException(\"Cannot start process instance. Process definition \"\r\n                    + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") is suspended\");\r\n        }\r\n\r\n        ActivityImpl startActivity = processDefinition.findActivity(messageEventSubscription.getActivityId());\r\n        ExecutionEntity processInstance = processDefinition.createProcessInstance(businessKey, startActivity);\r\n\r\n        if (processVariables != null) {\r\n            processInstance.setVariables(processVariables);\r\n        }\r\n        if (transientVariables != null) {\r\n            processInstance.setTransientVariables(transientVariables);\r\n        }\r\n\r\n        processInstance.start();\r\n\r\n        return processInstance;\r\n    }\r\n\r","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java#L72-L108","documentation":"Thrown by StartProcessInstanceByMessageCmd.execute() when the process definition that a message event subscription points to is currently suspended. The engine refuses to start new process instances from a suspended definition, since suspended definitions may not spawn new executions. It is a plain ActivitiException carrying the definition name and id.","triggerScenarios":"Calling RuntimeService.startProcessInstanceByMessage(...) (or message start event correlation) while the target process definition has been suspended via RepositoryService.suspendProcessDefinitionById/key (with or without includeProcessInstances).","commonSituations":"An admin suspended a definition version for a business freeze or a redeployment, and an application or message listener still correlates messages to that definition; batch jobs starting instances during a maintenance window; race between suspend operation and in-flight message delivery.","solutions":["Resume the definition first: RepositoryService.activateProcessDefinitionById(processDefinitionId) (or byKey), then retry starting the instance.","If suspension was intentional, stop sending/correlating messages to that definition and route to an active version or queue the messages until activation.","Check suspension state before starting: processDefinition.isSuspended() via RepositoryService.getProcessDefinition(id), and guard the call.","If a whole deployment is suspended, activate the deployment or the specific definition version your message start event belongs to."],"exampleFix":"// before\nruntimeService.startProcessInstanceByMessage(\"orderReceived\", businessKey, vars); // throws when suspended\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"orderProcess\").latestVersion().singleResult();\nif (pd.isSuspended()) {\n    repositoryService.activateProcessDefinitionById(pd.getId(), true, null);\n}\nruntimeService.startProcessInstanceByMessage(\"orderReceived\", businessKey, vars);","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionId(processDefinitionId).singleResult();\nif (pd == null || pd.isSuspended()) {\n    throw new IllegalStateException(\"Definition missing or suspended: \" + processDefinitionId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.startProcessInstanceByMessage(messageName, businessKey, vars);\n} catch (ActivitiException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"is suspended\")) {\n        repositoryService.activateProcessDefinitionByKey(definitionKey, true, null);\n        // retry once\n    } else {\n        throw e;\n    }\n}","preventionTips":["Check processDefinition.isSuspended() before starting instances","Track suspension windows in application state and stop producers during them","Re-activate definitions after scheduled maintenance with a scripted job","Alert on message correlation failures indicating suspended definitions"],"tags":["process-definition","suspended","workflow","message-start-event"],"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"}