flowable/flowable-engine · error · FlowableIllegalArgumentException

A resource name is mandatory

Error message

A resource name is mandatory

What it means

EventModelBuilderImpl.deploy() first validates that a resource name was provided, because the deployed event model must be stored under a named resource in the deployment. Deploying without one makes the persisted EventDefinitionEntity lack a resourceName, so Flowable throws this FlowableIllegalArgumentException before building the model.

Solutions

1. Call .resource("myEvent.event") on the builder before deploy()
2. If you only want the model without deployment, use createEventModel()/buildEventModel() instead of deploy()
3. Add a null/empty check on the resource name in deployment helper code before invoking the builder

Example fix

// before
eventRepositoryService.createEventModelBuilder()
    .key("orderCreated")
    .resourceNameFromString(...)  // model built, but resource never named
    .deploy();
// after
eventRepositoryService.createEventModelBuilder()
    .key("orderCreated")
    .resource("orderCreated.event")
    .deploy();

if (resourceName == null || resourceName.isEmpty()) {
    throw new IllegalArgumentException("resource(name) must be called before deploy()");
}

try {
    builder.deploy();
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("resource name is mandatory")) { /* fix builder calls */ }
}

When it happens

Trigger: Building an event model via EventRepositoryService.createEventModelBuilder() (or new EventModelBuilderImpl) and calling deploy() without ever calling resource(name).

Common situations: Programmatic event deployment where the developer sets key/payload but forgets resource(); refactored builder code where the resource() call was dropped; dynamic deployment scripts that only set the name for some branches.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• An event definition key is mandatory
• A channel key detection value is required for the channel…
• Event definition id is null
• eventDefinitionKey and eventDefinitionId are null
• EventRegistryEventDefinition on '" + elementId + "' has an…

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

Appendix: source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/model/EventModelBuilderImpl.java:131

        eventPayloadDefinitions.put(name, payload);
        return this;
    }

    @Override
    public EventModelBuilder fullPayload(String name) {
        eventPayloadDefinitions.put(name, EventPayload.fullPayload(name));
        return this;
    }

    @Override
    public EventModel createEventModel() {
        return buildEventModel();
    }

    @Override
    public EventDeployment deploy() {
        if (resourceName == null) {
            throw new FlowableIllegalArgumentException("A resource name is mandatory");
        }
        
        EventModel eventModel = buildEventModel();

        return eventRepository.createDeployment()
            .name(deploymentName)
            .addEventDefinition(resourceName, eventJsonConverter.convertToJson(eventModel))
            .category(category)
            .parentDeploymentId(parentDeploymentId)
            .tenantId(deploymentTenantId)
            .deploy();
    }

    protected EventModel buildEventModel() {
        EventModel eventModel = new EventModel();

        if (StringUtils.isNotEmpty(key)) {
            eventModel.setKey(key);

View on GitHub (pinned to d6d39ce1c6)