{"record":{"id":"e3f70e2b6e7b69cf","repo":"Activiti/Activiti","slug":"processdefinitionhelper-is-not-set-for-the-current","errorCode":null,"errorMessage":"ProcessDefinitionHelper is not set for the current context.","messagePattern":"ProcessDefinitionHelper is not set for the current context\\.","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/util/ProcessDefinitionUtil.java","lineNumber":64,"sourceCode":"                .getProcessDefinitionCache()\n                .get(processDefinitionId);\n            if (cacheEntry != null) {\n                return cacheEntry.getProcessDefinition();\n            }\n            return null;\n        } else {\n            // This will check the cache in the findDeployedProcessDefinitionById method\n            return processEngineConfiguration\n                .getDeploymentManager()\n                .findDeployedProcessDefinitionById(processDefinitionId);\n        }\n    }\n\n    public static ProcessDefinitionHelper getProcessDefinitionHelper() {\n        ProcessDefinitionHelper processDefinitionHelper = Context.getProcessDefinitionHelper();\n\n        if (processDefinitionHelper == null) {\n            throw new ActivitiException(\"ProcessDefinitionHelper is not set for the current context.\");\n        }\n        return processDefinitionHelper;\n    }\n\n    public static Process getProcess(String processDefinitionId) {\n        if (Context.getProcessEngineConfiguration() == null) {\n            return getProcessDefinitionHelper().getProcessDefinitionProcessObject(processDefinitionId);\n        } else {\n            DeploymentManager deploymentManager = Context.getProcessEngineConfiguration().getDeploymentManager();\n\n            // This will check the cache in the findDeployedProcessDefinitionById and resolveProcessDefinition method\n            ProcessDefinition processDefinitionEntity = deploymentManager.findDeployedProcessDefinitionById(\n                processDefinitionId\n            );\n            return deploymentManager.resolveProcessDefinition(processDefinitionEntity).getProcess();\n        }\n    }\n","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/Activiti/Activiti/blob/56435b1a97deeafdc09dd40074b056c89fba5a8a/activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/util/ProcessDefinitionUtil.java#L46-L82","documentation":"ProcessDefinitionUtil.getProcessDefinitionHelper() requires a ProcessDefinitionHelper to be installed on the current thread's Context (typically set up by the engine's command context). When the utility is invoked outside an engine-managed command execution, the helper is null and Activiti throws a plain ActivitiException.","triggerScenarios":"Calling ProcessDefinitionUtil.getProcess() or getBpmnModel() from a non-command thread, a unit test, a Spring bean, or custom code that never runs inside CommandExecutor/CommandContext.","commonSituations":"Unit tests calling these static helpers directly without opening a command context; background jobs reusing engine utilities outside the engine; custom interceptors replacing the default context setup.","solutions":["Run the code inside the engine: processEngineConfiguration.getCommandExecutor().execute(context -> { ... }) so Context gets initialized","Use the public APIs (RepositoryService.getBpmnModel(...)) instead of the internal ProcessDefinitionUtil helpers","In tests, wrap calls in managementService.executeCommand(new Command<Void>() {...})","If writing custom code that must install the helper, call Context.setProcessDefinitionHelper(...) before use and clean it up after"],"exampleFix":"// before\nProcess p = ProcessDefinitionUtil.getProcess(definitionId);\n// after\nProcess p = repositoryService.getBpmnModel(definitionId)\n    .getMainProcess();","handlingStrategy":"try-catch","validationCode":"if (Context.getProcessEngineConfiguration() == null) {\n    throw new IllegalStateException(\"Not inside a command context; use repositoryService API instead\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Process p = ProcessDefinitionUtil.getProcess(defId);\n} catch (ActivitiException e) {\n    // fall back to public API\n    Process p = repositoryService.getBpmnModel(defId).getMainProcess();\n}","preventionTips":["Prefer public service APIs (RepositoryService/RuntimeService) over internal *Util helpers","Wrap any internal utility use inside managementService.executeCommand(...) in tests","Never call engine internals from threads not managed by the CommandExecutor"],"tags":["command-context","internal-api","thread-context"],"backgroundTag":"missing-required-config","analyzedSha":"56435b1a97deeafdc09dd40074b056c89fba5a8a","analyzedAt":"2026-09-09T21:00:06.703Z","contentChangedAt":"2026-09-09T21:00:06.703Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}