{"record":{"id":"8350269a806c4371","repo":"flowable/flowable-engine","slug":"cannot-execute-operation-because-process-definitio","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":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/NeedsActiveProcessDefinitionCmd.java","lineNumber":42,"sourceCode":"/**\n * @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        ProcessDefinitionEntity processDefinition = ProcessDefinitionUtil.getProcessDefinitionFromDatabase(processDefinitionId);\n\n        if (processDefinition.isSuspended()) {\n            throw new FlowableException(\"Cannot execute operation because process definition '\" + 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, ProcessDefinitionEntity processDefinition);\n\n}\n","sourceCodeStart":24,"sourceCodeEnd":54,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/NeedsActiveProcessDefinitionCmd.java#L24-L54","documentation":"Flowable throws this FlowableException when a command extending NeedsActiveProcessDefinitionCmd (e.g. start a process instance by id) targets a process definition that is currently suspended. Definitions are suspended/activated via RepositoryService, and all runtime operations against a suspended definition are blocked.","triggerScenarios":"Calling RuntimeService.startProcessInstanceById(processDefinitionId) (or other NeedsActiveProcessDefinitionCmd subclasses) while the definition was suspended with RepositoryService.suspendProcessDefinitionById(...).","commonSituations":"Ops suspended a definition version to deploy a fix, but clients still start instances by that id; a suspended definition is the default/latest version so new starts fail; environment sync copied suspended state across environments.","solutions":["Reactivate with repositoryService.activateProcessDefinitionById(processDefinitionId) (optionally suspend/activate related instances too), then retry.","Use a different active definition version: startProcessInstanceByKey with the latest active version instead of a suspended id.","Check suspension up front: RepositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult().isSuspended().","Catch FlowableException with message matching \"is suspended\" and return a clear business error to the caller."],"exampleFix":"// before\nruntimeService.startProcessInstanceById(\"suspended-def-id\");\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(\"suspended-def-id\").singleResult();\nif (pd != null && !pd.isSuspended()) {\n    runtimeService.startProcessInstanceById(pd.getId());\n}","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(defId).singleResult();\nif (pd == null || pd.isSuspended()) { throw new IllegalStateException(\"Definition missing or suspended\"); }","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.startProcessInstanceById(defId);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"is suspended\")) {\n        repositoryService.activateProcessDefinitionById(defId);\n        return runtimeService.startProcessInstanceById(defId);\n    }\n    throw e;\n}","preventionTips":["Start instances by key so Flowable resolves the latest active version.","Monitor for suspended definitions after deployments.","Automate suspend/activate pairs so definitions are never left suspended.","Add integration tests that start instances after migration runs."],"tags":["flowable","suspended-process-definition","invalid-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"}