flowable/flowable-engine · error · ActivitiException

exception during timer execution: ${message}

Error message

exception during timer execution: ${message}

What it means

Same wrapping pattern as TimerExecuteNestedActivityJobHandler: checked Exceptions thrown while starting a new process instance from a timer start event are caught, logged, and rethrown as ActivitiException('exception during timer execution: ' + message). RuntimeExceptions pass through unchanged. The meaningful cause is the wrapped exception.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/jobexecutor/TimerStartEventJobHandler.java:105

        if (processDefinition == null) {
            throw new ActivitiException("Could not find process definition needed for timer start event");
        }

        try {
            if (!deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {
                dispatchTimerFiredEvent(job, commandContext);

                new StartProcessInstanceCmd<ProcessInstance>(processDefinitionKey, null, null, null, job.getTenantId()).execute(commandContext);
            } else {
                LOGGER.debug("Ignoring timer of suspended process definition {}", processDefinition.getId());
            }
        } catch (RuntimeException e) {
            LOGGER.error("exception during timer execution", e);
            throw e;
        } catch (Exception e) {
            LOGGER.error("exception during timer execution", e);
            throw new ActivitiException("exception during timer execution: " + e.getMessage(), e);
        }
    }

    protected void dispatchTimerFiredEvent(Job job, CommandContext commandContext) {
        if (commandContext.getEventDispatcher().isEnabled()) {
            commandContext.getEventDispatcher().dispatchEvent(
                    ActivitiEventBuilder.createEntityEvent(FlowableEngineEventType.TIMER_FIRED, job),
                    EngineConfigurationConstants.KEY_PROCESS_ENGINE_CONFIG);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Inspect exception.getCause() and the log entry 'exception during timer execution' for the root cause; fix that first
2. Check whether custom FlowableEventListener implementations on the event dispatcher throw checked exceptions and wrap them in FlowableException
3. Verify the async executor's classpath includes all delegates/listeners used by the timer-started process
4. Retry the job after the fix (managementService or reset retries) since the timer start will re-fire on schedule anyway

Example fix

// before: listener throws checked exception during TIMER_FIRED dispatch
public void onEvent(FlowableEvent event) throws Exception { send(event); }
// after
public void onEvent(FlowableEvent event) {
  try { send(event); } catch (IOException e) { throw new FlowableException("dispatch failed", e); }
}

// Pre-check that the timer-started process can be instantiated
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(key).latestVersion().singleResult();
if (pd == null || pd.isSuspended()) throw new IllegalStateException("definition not startable: " + key);

try {
  managementService.executeJob(startTimerJobId);
} catch (FlowableException e) {
  Throwable root = e; while (root.getCause() != null) root = root.getCause();
  log.error("timer start execution failed, root: {}", root.getMessage(), root);
}

When it happens

Trigger: A checked Exception occurs during startProcessDefinitionByKey execution after the definition lookup succeeded — e.g. while dispatching the TIMER_FIRED event or while starting the process instance (startProcessInstanceByKey path).

Common situations: Event dispatcher listeners throwing checked exceptions; failures instantiating the process instance (missing start form variables, delegate initialization errors); environment/classpath problems in the async executor thread.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Job ${jobId} failed
• exception during timer execution: ${message}
• Could not find process definition needed for timer start eve
• e.getMessage()
• Exception while processing exchange

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/1f1e9fe827dcba2b. Report an issue: GitHub.