{"record":{"id":"98b2e356443e89de","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-process-definition-98b2e3","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/StartProcessInstanceCmd.java","lineNumber":98,"sourceCode":"                throw new ActivitiObjectNotFoundException(\"No process definition found for id = '\" + processDefinitionId + \"'\", ProcessDefinition.class);\n            }\n        } else if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {\n            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitionKey);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"'\", ProcessDefinition.class);\n            }\n        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\n            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"' for tenant identifier \" + tenantId, ProcessDefinition.class);\n            }\n        } else {\n            throw new ActivitiIllegalArgumentException(\"processDefinitionKey and processDefinitionId are null\");\n        }\n\n        // Do not start process a process instance if the process definition is suspended\n        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {\n            throw new ActivitiException(\"Cannot start process instance. Process definition \"\n                    + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") is suspended\");\n        }\n\n        // Start the process instance\n        ExecutionEntity processInstance = ((ProcessDefinitionEntity) processDefinition).createProcessInstance(businessKey);\n\n        // now set the variables passed into the start command\n        initializeVariables(processInstance);\n\n        // now set processInstance name\n        if (processInstanceName != null) {\n            processInstance.setName(processInstanceName);\n            commandContext.getHistoryManager().recordProcessInstanceNameChange(processInstance.getId(), processInstanceName);\n        }\n\n        processInstance.start();\n\n        return processInstance;","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java#L80-L116","documentation":"Thrown by StartProcessInstanceCmd.execute() as ActivitiException when the resolved process definition is suspended; the engine refuses to create a new process instance. The message names the definition's name and id so the offending definition is easy to identify.","triggerScenarios":"RuntimeService.startProcessInstanceById/ByKey after the target definition was suspended via RepositoryService.suspendProcessDefinitionById/Key(...); scheduled starters or API endpoints invoked during a business suspension window.","commonSituations":"Maintenance/business freezes where definitions are suspended intentionally; redeployments that suspend old versions while clients still call the old key/version; default behavior of suspending a definition without realizing it blocks new instances.","solutions":["Activate it: RepositoryService.activateProcessDefinitionById(id, includeProcessInstances, activationDate) or activateProcessDefinitionByKey, then retry.","If the suspension is intentional, block new starts in the application and reject/queue requests gracefully.","Start from a non-suspended version: choose an active latest version via ProcessDefinitionQuery().active().latestVersion().","Check isSuspended() on the definition before starting and surface a friendly error to users."],"exampleFix":"// before\nruntimeService.startProcessInstanceByKey(\"orderProcess\"); // throws: definition suspended\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"orderProcess\").latestVersion().singleResult();\nif (pd.isSuspended()) {\n    repositoryService.activateProcessDefinitionById(pd.getId(), true, null);\n}\nruntimeService.startProcessInstanceByKey(\"orderProcess\");","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(definitionKey).latestVersion().singleResult();\nif (pd != null && pd.isSuspended()) {\n    throw new IllegalStateException(\"Definition suspended: \" + pd.getName());\n}","typeGuard":null,"tryCatchPattern":"try {\n    return runtimeService.startProcessInstanceByKey(definitionKey, vars);\n} catch (ActivitiException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"is suspended\")) {\n        throw new ProcessSuspendedException(definitionKey, e);\n    }\n    throw e;\n}","preventionTips":["Query with .active() to select only active versions for starting","Expose suspension state in admin UI so operators know the impact of suspending","Use suspendProcessDefinition with an explicit activationDate to auto-resume","Document suspension procedures so callers stop/start in sync"],"tags":["process-definition","suspended","workflow"],"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"}