Activiti/Activiti · error · ActivitiException

ProcessDefinitionHelper is not set for the current context.

Error message

ProcessDefinitionHelper is not set for the current context.

What it means

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.

Solutions

1. Run the code inside the engine: processEngineConfiguration.getCommandExecutor().execute(context -> { ... }) so Context gets initialized
2. Use the public APIs (RepositoryService.getBpmnModel(...)) instead of the internal ProcessDefinitionUtil helpers
3. In tests, wrap calls in managementService.executeCommand(new Command<Void>() {...})
4. If writing custom code that must install the helper, call Context.setProcessDefinitionHelper(...) before use and clean it up after

Example fix

// before
Process p = ProcessDefinitionUtil.getProcess(definitionId);
// after
Process p = repositoryService.getBpmnModel(definitionId)
    .getMainProcess();

if (Context.getProcessEngineConfiguration() == null) {
    throw new IllegalStateException("Not inside a command context; use repositoryService API instead");
}

try {
    Process p = ProcessDefinitionUtil.getProcess(defId);
} catch (ActivitiException e) {
    // fall back to public API
    Process p = repositoryService.getBpmnModel(defId).getMainProcess();
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• exception while executing command
• lazy loading outside command context
• lazy loading outside command context
• lazy loading outside command context
• no session factory configured for

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/e3f70e2b6e7b69cf. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/util/ProcessDefinitionUtil.java:64

                .getProcessDefinitionCache()
                .get(processDefinitionId);
            if (cacheEntry != null) {
                return cacheEntry.getProcessDefinition();
            }
            return null;
        } else {
            // This will check the cache in the findDeployedProcessDefinitionById method
            return processEngineConfiguration
                .getDeploymentManager()
                .findDeployedProcessDefinitionById(processDefinitionId);
        }
    }

    public static ProcessDefinitionHelper getProcessDefinitionHelper() {
        ProcessDefinitionHelper processDefinitionHelper = Context.getProcessDefinitionHelper();

        if (processDefinitionHelper == null) {
            throw new ActivitiException("ProcessDefinitionHelper is not set for the current context.");
        }
        return processDefinitionHelper;
    }

    public static Process getProcess(String processDefinitionId) {
        if (Context.getProcessEngineConfiguration() == null) {
            return getProcessDefinitionHelper().getProcessDefinitionProcessObject(processDefinitionId);
        } else {
            DeploymentManager deploymentManager = Context.getProcessEngineConfiguration().getDeploymentManager();

            // This will check the cache in the findDeployedProcessDefinitionById and resolveProcessDefinition method
            ProcessDefinition processDefinitionEntity = deploymentManager.findDeployedProcessDefinitionById(
                processDefinitionId
            );
            return deploymentManager.resolveProcessDefinition(processDefinitionEntity).getProcess();
        }
    }

View on GitHub (pinned to 56435b1a97)